Add bulk evaluation

.changeset/adapter-bulk-evaluation.md

@@ -0,0 +1,9 @@
+---
+'@flags-sdk/vercel': minor
+---
+
+Faster evaluation of flags when using the Vercel adapter via `bulk()`.
+
+This version of `flags-sdk/vercel` implements `bulkDecide` on the Vercel Flags adapter so flags can be evaluated together via `bulk()` from `flags/next`.
+
+This improves performance by avoiding the per-flag overhead of separate `evaluate()` calls. We've seen a 10x improvement in evaluation time for large batches of flags.

.changeset/core-bulk-evaluation.md

@@ -0,0 +1,20 @@
+---
+'@vercel/flags-core': minor
+---
+
+Add `bulkEvaluate` method to `FlagsClient` for resolving multiple flags against shared entities in a single call.
+
+```ts
+const results = await client.bulkEvaluate(
+  [
+    { key: 'a', defaultValue: false },
+    { key: 'b', defaultValue: 'off' },
+  ],
+  entities,
+);
+
+results.a; // EvaluationResult<boolean>
+results.b; // EvaluationResult<string>
+```
+
+Avoids the per-flag overhead of separate `evaluate()` calls — the datafile is read once, entities are resolved once, and all flags share the same environment/segments lookup. Each entry in the returned record is a full `EvaluationResult` with `value`, `reason`, `outcomeType`, and `metrics`.

.changeset/flags-bulk-evaluation.md

@@ -0,0 +1,18 @@
+---
+'flags': minor
+---
+
+Add `bulk()` function for evaluating multiple flags in a single call from the `flags/next` entry point.
+
+```tsx
+import { bulk } from 'flags/next';
+import { flagA, flagB } from '../flags';
+
+// pass a list of flags
+const [valueA, valueB] = await bulk([flagA, flagB]);
+
+// pass an object
+const { a, b } = await bulk({ a: flagA, b: flagB });
+```
+
+Adapters can now opt into batched evaluation by implementing an optional `bulkDecide` method and setting a stable `adapterId`. When both are present, `bulk()` groups flags that share the same `adapterId` and `identify` source and invokes `bulkDecide` once per group instead of calling `decide` per flag. Flags without a bulk-capable adapter (or with an inline `decide`) still resolve through the normal per-flag path inside `bulk()` and benefit from the shared per-request headers, cookies, and overrides reads.

package.json

@@ -27,6 +27,7 @@
     "shirt-shop": "pnpm dev -F shirt-shop",
     "shirt-shop-api": "pnpm dev -F shirt-shop-api",
     "snippets": "pnpm dev -F snippets",
+    "playground": "pnpm dev -F playground",
     "svelte": "pnpm dev -F svelte-example",
     "test": "turbo test",
     "test:e2e": "turbo test:e2e",

packages/adapter-vercel/src/index.test.ts

@@ -117,6 +117,72 @@ describe('createVercelAdapter', () => {
       .toHaveProperty('entities')
       .toEqualTypeOf<SampleEvaluationContext | undefined>();
   });
+
+  describe('adapterId', () => {
+    it('shares one adapterId across all adapters from the same factory call', () => {
+      const adapter = createVercelAdapter(flagsClient);
+      const a = adapter();
+      const b = adapter();
+      expect(a).not.toBe(b);
+      expect(a.adapterId).toBeDefined();
+      expect(a.adapterId).toBe(b.adapterId);
+    });
+
+    it('uses different adapterIds across separate factory calls', () => {
+      const adapterA = createVercelAdapter('vf_client_key_a');
+      const adapterB = createVercelAdapter('vf_client_key_b');
+      expect(adapterA().adapterId).not.toBe(adapterB().adapterId);
+    });
+  });
+
+  describe('bulkDecide', () => {
+    it('forwards to flagsClient.bulkEvaluate with mapped flags and entities', async () => {
+      const bulkEvaluateMock = vi
+        .fn()
+        .mockResolvedValue({ a: { value: 'x' }, b: { value: 'y' } });
+      const fakeClient = {
+        origin: { provider: 'vercel', sdkKey: 'vf_x' },
+        bulkEvaluate: bulkEvaluateMock,
+      } as unknown as typeof flagsClient;
+
+      const adapter = createVercelAdapter(fakeClient)();
+      const result = await adapter.bulkDecide!({
+        flags: [{ key: 'a', defaultValue: 'da' }, { key: 'b' }],
+        entities: { user: { id: 'u1' } } as any,
+        headers: undefined as any,
+        cookies: undefined as any,
+      });
+
+      expect(bulkEvaluateMock).toHaveBeenCalledTimes(1);
+      expect(bulkEvaluateMock).toHaveBeenCalledWith(
+        [
+          { key: 'a', defaultValue: 'da' },
+          { key: 'b', defaultValue: undefined },
+        ],
+        { user: { id: 'u1' } },
+      );
+      expect(result).toEqual({ a: 'x', b: 'y' });
+    });
+
+    it('omits keys whose EvaluationResult.value is undefined', async () => {
+      const fakeClient = {
+        origin: { provider: 'vercel', sdkKey: 'vf_x' },
+        bulkEvaluate: vi.fn().mockResolvedValue({
+          a: { value: 'ok' },
+          b: { value: undefined, reason: 'error', errorMessage: 'nope' },
+        }),
+      } as unknown as typeof flagsClient;
+
+      const adapter = createVercelAdapter(fakeClient)();
+      const result = await adapter.bulkDecide!({
+        flags: [{ key: 'a' }, { key: 'b' }],
+        headers: undefined as any,
+        cookies: undefined as any,
+      });
+      expect(result).toEqual({ a: 'ok' });
+      expect('b' in result).toBe(false);
+    });
+  });
 });
 
 describe('when used with getProviderData', () => {

packages/adapter-vercel/src/index.ts

@@ -30,11 +30,18 @@ export function createVercelAdapter(
       ? createClient(sdkKeyOrFlagsClient)
       : sdkKeyOrFlagsClient;
 
+  // Stable identity for this adapter's underlying flagsClient. Captured in
+  // the closure so every adapter object the factory below returns shares it,
+  // letting `bulk()` group flags from multiple `vercelAdapter()` calls into
+  // a single `bulkDecide` invocation.
+  const adapterId = Symbol('vercelAdapter');
+
   return function vercelAdapter<ValueType, EntitiesType>(): Adapter<
     ValueType,
     EntitiesType
   > {
     return {
+      adapterId,
       origin: flagsClient.origin,
       config: { reportValue: false },
       async decide({ key, entities }): Promise<ValueType> {
@@ -57,6 +64,20 @@ export function createVercelAdapter(
         // when there was an error but the defaultValue was set
         return evaluationResult.value;
       },
+      async bulkDecide({ flags, entities }) {
+        const results = await flagsClient.bulkEvaluate<ValueType, EntitiesType>(
+          flags,
+          entities,
+        );
+        const out: Record<string, ValueType> = {};
+        for (const key in results) {
+          const r = results[key]!;
+          // Omit undefined so the SDK applies the per-flag `defaultValue`
+          // fallback (matches single-decide semantics).
+          if (r.value !== undefined) out[key] = r.value;
+        }
+        return out;
+      },
     };
   };
 }