add mergeProviderData

.changeset/light-shirts-fix.md

@@ -0,0 +1,33 @@
+---
+'@vercel/flags': minor
+---
+
+Add `mergeProviderData` function to `@vercel/flags`.
+
+This function allows merging ProviderData from multiple sources.
+
+This is handy when you declare feature flags in code, and want to extend those definitions with data loaded from your feature flag provider.
+
+```ts
+import { verifyAccess, mergeProviderData, type ApiData } from '@vercel/flags';
+import { getProviderData } from '@vercel/flags/next';
+import { NextResponse, type NextRequest } from 'next/server';
+import { getProviderData as getStatsigProviderData } from '@flags-sdk/statsig';
+import * as flagsA from '../../../../flags-a'; // your feature flags file(s)
+import * as flagsB from '../../../../flags-b'; // your feature flags file(s)
+
+export async function GET(request: NextRequest) {
+  const access = await verifyAccess(request.headers.get('Authorization'));
+  if (!access) return NextResponse.json(null, { status: 401 });
+
+  const providerData = await mergeProviderData([
+    // expose flags declared in code first
+    getProviderData(flagsA),
+    getProviderData(flagsB),
+    // then enhance them with metadata from your flag provider
+    getStatsigProviderData({ consoleApiKey: '', projectId: '' }),
+  ]);
+
+  return NextResponse.json<ApiData>(providerData);
+}
+```

packages/flags/src/index.ts

@@ -25,3 +25,4 @@ export {
   type ReadonlyRequestCookies,
   RequestCookiesAdapter,
 } from './spec-extension/adapters/request-cookies';
+export { mergeProviderData } from './lib/merge-provider-data';

packages/flags/src/lib/merge-provider-data.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+import { mergeProviderData } from './merge-provider-data';
+
+describe('mergeProviderData', async () => {
+  it('returns empty providerData when called with an empty array', async () => {
+    await expect(mergeProviderData([])).resolves.toEqual({
+      definitions: {},
+      hints: [],
+    });
+  });
+
+  it('merges providerData from top to bottom', async () => {
+    await expect(
+      mergeProviderData([
+        { definitions: { a: { description: 'desc1' } }, hints: [] },
+        { definitions: { a: { description: 'desc2' } }, hints: [] },
+      ]),
+    ).resolves.toEqual({
+      definitions: {
+        a: { description: 'desc2' },
+      },
+      hints: [],
+    });
+  });
+
+  it('merges providerData of different flags', async () => {
+    await expect(
+      mergeProviderData([
+        { definitions: { a: { description: 'descA' } }, hints: [] },
+        { definitions: { b: { description: 'descB' } }, hints: [] },
+      ]),
+    ).resolves.toEqual({
+      definitions: {
+        a: { description: 'descA' },
+        b: { description: 'descB' },
+      },
+      hints: [],
+    });
+  });
+
+  it('merges hints', async () => {
+    await expect(
+      mergeProviderData([
+        {
+          definitions: {},
+          hints: [{ key: 'hintA', text: 'hintA' }],
+        },
+        {
+          definitions: {},
+          hints: [{ key: 'hintB', text: 'hintB' }],
+        },
+      ]),
+    ).resolves.toEqual({
+      definitions: {},
+      hints: [
+        { key: 'hintA', text: 'hintA' },
+        { key: 'hintB', text: 'hintB' },
+      ],
+    });
+  });
+
+  it('merges complex cases', async () => {
+    await expect(
+      mergeProviderData([
+        {
+          definitions: {
+            a: {
+              description: 'descA',
+              declaredInCode: true,
+              options: [
+                { label: 'nope', value: false },
+                { label: 'nope', value: true },
+              ],
+            },
+            b: { description: 'descB' },
+          },
+          hints: [{ key: 'hintA', text: 'hintA' }],
+        },
+        {
+          definitions: {
+            a: {
+              options: [
+                { label: 'Off', value: false },
+                { label: 'On', value: true },
+              ],
+            },
+          },
+          hints: [],
+        },
+        {
+          definitions: {
+            c: { description: 'descC' },
+          },
+          hints: [],
+        },
+      ]),
+    ).resolves.toEqual({
+      definitions: {
+        a: {
+          description: 'descA',
+          declaredInCode: true,
+          options: [
+            { label: 'Off', value: false },
+            { label: 'On', value: true },
+          ],
+        },
+        b: { description: 'descB' },
+        c: { description: 'descC' },
+      },
+      hints: [{ key: 'hintA', text: 'hintA' }],
+    });
+  });
+
+  it('ignores rejected promises', async () => {
+    await expect(
+      mergeProviderData([
+        Promise.resolve({
+          definitions: {},
+          hints: [{ key: 'hintA', text: 'hintA' }],
+        }),
+        Promise.reject(new Error('error')),
+        Promise.resolve({
+          definitions: {},
+          hints: [{ key: 'hintB', text: 'hintB' }],
+        }),
+      ]),
+    ).resolves.toEqual({
+      definitions: {},
+      hints: [
+        { key: 'hintA', text: 'hintA' },
+        { key: 'hintB', text: 'hintB' },
+      ],
+    });
+  });
+});

packages/flags/src/lib/merge-provider-data.ts

@@ -0,0 +1,25 @@
+import { ProviderData } from '../types';
+
+export async function mergeProviderData(
+  itemsPromises: (Promise<ProviderData> | ProviderData)[],
+): Promise<ProviderData> {
+  const items = await Promise.all(
+    itemsPromises.map((p) => Promise.resolve(p).catch(() => null)),
+  );
+
+  return items
+    .filter((item): item is ProviderData => Boolean(item))
+    .reduce<ProviderData>(
+      (acc, item) => {
+        Object.entries(item.definitions).forEach(([key, definition]) => {
+          if (!acc.definitions[key]) acc.definitions[key] = {};
+          Object.assign(acc.definitions[key], definition);
+        });
+
+        if (Array.isArray(item.hints)) acc.hints.push(...item.hints);
+
+        return acc;
+      },
+      { definitions: {}, hints: [] },
+    );
+}