fix(flags): handle plain array and object forms in overrideFeatureFlags (#3245)

* fix overrides

* Address PR feedback: extract helper and use parameterised tests

- Extract arrayToFlagsRecord helper to eliminate duplicated array-to-flags-object conversion
- Refactor tests to use it.each for parameterised testing

* Address PR feedback: narrow return type and log invalid options

- Narrow arrayToFlagsRecord return type from Record<string, string | boolean> to Record<string, true>
- Replace unreachable _fireFeatureFlagsCallbacks call with warning log for invalid overrideOptions

* add changeset

Author: dmarticus

.changeset/honest-rats-raise.md

@@ -0,0 +1,6 @@
+---
+'posthog-js': patch
+'@posthog/types': patch
+---
+
+handle plain array and object forms in overrideFeatureFlags

packages/browser/src/__tests__/featureflags.test.ts

@@ -958,6 +958,33 @@ describe('featureflags', () => {
             })
         })
 
+        describe('plain array and object shorthand forms', () => {
+            it.each([
+                ['plain array', ['beta-feature', 'alpha-feature-2'], { 'beta-feature': true, 'alpha-feature-2': true }],
+                [
+                    'plain object',
+                    { 'beta-feature': 'variant-1', 'alpha-feature-2': false },
+                    { 'beta-feature': 'variant-1', 'alpha-feature-2': false },
+                ],
+            ])('supports %s shorthand form for flag overrides', (_, input, expected) => {
+                featureFlags.overrideFeatureFlags(input as any)
+                expect(featureFlags.getFlagVariants()).toEqual(expected)
+            })
+
+            it('plain object does not affect payloads', () => {
+                featureFlags.overrideFeatureFlags({ 'beta-feature': 'variant-1' })
+
+                expect(featureFlags.getFlagVariants()).toEqual({
+                    'beta-feature': 'variant-1',
+                    'alpha-feature-2': true,
+                })
+                expect(featureFlags.getFlagPayloads()).toEqual({
+                    'beta-feature': { original: 'payload' },
+                    'alpha-feature-2': 123,
+                })
+            })
+        })
+
         describe('callback behavior', () => {
             let callbackSpy: jest.Mock
 

packages/browser/src/posthog-featureflags.ts

@@ -61,6 +61,15 @@ const PERSISTENCE_FEATURE_FLAG_PAYLOADS = '$feature_flag_payloads'
 const PERSISTENCE_OVERRIDE_FEATURE_FLAG_PAYLOADS = '$override_feature_flag_payloads'
 const PERSISTENCE_FEATURE_FLAG_REQUEST_ID = '$feature_flag_request_id'
 
+/** Converts an array of flag names to a Record where each flag is set to true. */
+const arrayToFlagsRecord = (flags: string[]): Record<string, true> => {
+    const flagsObj: Record<string, true> = {}
+    for (let i = 0; i < flags.length; i++) {
+        flagsObj[flags[i]] = true
+    }
+    return flagsObj
+}
+
 export const filterActiveFeatureFlags = (featureFlags?: Record<string, string | boolean>) => {
     const activeFeatureFlags: Record<string, string | boolean> = {}
     for (const [key, value] of entries(featureFlags || {})) {
@@ -946,6 +955,8 @@ export class PostHogFeatureFlags implements Extension {
      *     - posthog.featureFlags.overrideFeatureFlags(false) // clear all overrides
      *     - posthog.featureFlags.overrideFeatureFlags(['beta-feature']) // enable flags
      *     - posthog.featureFlags.overrideFeatureFlags({'beta-feature': 'variant'}) // set variants
+     *     - posthog.featureFlags.overrideFeatureFlags({ flags: ['beta-feature'] }) // enable flags
+     *     - posthog.featureFlags.overrideFeatureFlags({ flags: {'beta-feature': 'variant'} }) // set variants
      *     - posthog.featureFlags.overrideFeatureFlags({ // set both flags and payloads
      *         flags: {'beta-feature': 'variant'},
      *         payloads: { 'beta-feature': { someData: true } }
@@ -968,6 +979,15 @@ export class PostHogFeatureFlags implements Extension {
             return forceDebugLogger.info('All overrides cleared')
         }
 
+        // Array syntax: ['flag-a', 'flag-b'] -> { 'flag-a': true, 'flag-b': true }
+        if (isArray(overrideOptions)) {
+            const flagsObj = arrayToFlagsRecord(overrideOptions)
+            this._instance.persistence.register({ [PERSISTENCE_OVERRIDE_FEATURE_FLAGS]: flagsObj })
+            this._fireFeatureFlagsCallbacks()
+
+            return forceDebugLogger.info('Flag overrides set', { flags: overrideOptions })
+        }
+
         if (
             overrideOptions &&
             typeof overrideOptions === 'object' &&
@@ -983,10 +1003,7 @@ export class PostHogFeatureFlags implements Extension {
                     forceDebugLogger.info('Flag overrides cleared')
                 } else if (options.flags) {
                     if (isArray(options.flags)) {
-                        const flagsObj: Record<string, string | boolean> = {}
-                        for (let i = 0; i < options.flags.length; i++) {
-                            flagsObj[options.flags[i]] = true
-                        }
+                        const flagsObj = arrayToFlagsRecord(options.flags)
                         this._instance.persistence.register({ [PERSISTENCE_OVERRIDE_FEATURE_FLAGS]: flagsObj })
                     } else {
                         this._instance.persistence.register({ [PERSISTENCE_OVERRIDE_FEATURE_FLAGS]: options.flags })
@@ -1013,7 +1030,17 @@ export class PostHogFeatureFlags implements Extension {
             return
         }
 
-        this._fireFeatureFlagsCallbacks()
+        // Fallback: treat as Record<string, string | boolean>, e.g. {'beta-feature': 'variant'}
+        if (overrideOptions && typeof overrideOptions === 'object') {
+            this._instance.persistence.register({
+                [PERSISTENCE_OVERRIDE_FEATURE_FLAGS]: overrideOptions as Record<string, string | boolean>,
+            })
+            this._fireFeatureFlagsCallbacks()
+
+            return forceDebugLogger.info('Flag overrides set', { flags: overrideOptions })
+        }
+
+        logger.warn('Invalid overrideOptions provided to overrideFeatureFlags', { overrideOptions })
     }
 
     /*

packages/types/src/posthog.ts

@@ -218,6 +218,9 @@ export interface PostHog {
          *     flags: {'beta-feature': 'variant'},
          *     payloads: { 'beta-feature': { someData: true } }
          * })
+         * posthog.featureFlags.overrideFeatureFlags({ // only override payloads
+         *     payloads: { 'beta-feature': { someData: true } }
+         * })
          * ```
          */
         overrideFeatureFlags(overrideOptions: OverrideFeatureFlagsOptions): void