feature-flag-patterns

name	feature-flag-patterns
description	Gradual rollout strategies, kill switches, A/B testing integration, flag lifecycle management, and technical debt prevention.

Feature Flag Patterns

Feature flag strategies for safe deployments, experimentation, and operational control.

Flag Types and Structure

interface FeatureFlag {
  key: string
  type: 'boolean' | 'percentage' | 'variant' | 'segment'
  enabled: boolean
  description: string
  owner: string              // Team/person responsible
  createdAt: Date
  expiresAt?: Date           // Auto-cleanup reminder
  tags: string[]             // 'release', 'experiment', 'ops', 'permission'
}

// Flag categories by lifecycle
enum FlagCategory {
  RELEASE = 'release',       // Temporary: ship behind flag, remove after rollout
  EXPERIMENT = 'experiment', // Temporary: A/B test, remove after analysis
  OPS = 'ops',               // Long-lived: kill switches, circuit breakers
  PERMISSION = 'permission', // Long-lived: premium features, entitlements
}

// Flag configuration
const FLAGS: Record<string, FeatureFlag> = {
  'new-checkout-flow': {
    key: 'new-checkout-flow',
    type: 'percentage',
    enabled: true,
    description: 'Redesigned checkout with fewer steps',
    owner: 'checkout-team',
    createdAt: new Date('2025-01-15'),
    expiresAt: new Date('2025-04-15'),   // 3 month max
    tags: ['release'],
  },
  'emergency-read-only': {
    key: 'emergency-read-only',
    type: 'boolean',
    enabled: false,
    description: 'Kill switch: disable all write operations',
    owner: 'platform-team',
    createdAt: new Date('2024-06-01'),
    tags: ['ops'],
  },
}

Gradual Rollout

class FeatureFlagService {
  constructor(private store: FlagStore) {}

  // Percentage-based rollout using consistent hashing
  isEnabled(flagKey: string, userId: string): boolean {
    const flag = this.store.getFlag(flagKey)
    if (!flag || !flag.enabled) return false

    switch (flag.type) {
      case 'boolean':
        return flag.enabled

      case 'percentage': {
        // Consistent: same user always gets same result for same flag
        const hash = this.consistentHash(flagKey, userId)
        return hash < (flag.percentage ?? 0)
      }

      case 'segment':
        return this.isInSegment(userId, flag.segments ?? [])

      case 'variant':
        return true  // Use getVariant() instead
    }
  }

  // Deterministic hash: user always gets same bucket for same flag
   (: , : ):  {
     input = 
     hash = 
     ( i = ; i < input.; i++) {
       char = input.(i)
      hash = ((hash << ) - hash) + char
      hash = hash & hash  
    }
     .(hash) %   
  }

  
  (: , : ):  {
     flag = ..(flagKey)
     (!flag?. || !flag.)  

     hash = .(flagKey, userId)
     cumulative = 
     ( variant  flag.) {
      cumulative += variant.
       (hash < cumulative)  variant.
    }
     
  }

  
   (: , : []):  {
     user = ..(userId)
     segments.( {
       (segment.) {
         :  segment..(userId)
         :  user?.[segment.] === segment.
         :  .(segment., userId) < segment.
      }
    })
  }
}

Kill Switch Pattern

// Operational flags: immediately disable features under load
class KillSwitch {
  private cache = new Map<string, { value: boolean; expiry: number }>()
  private pollInterval: NodeJS.Timeout

  constructor(private store: FlagStore, pollMs: number = 5000) {
    // Poll every 5s for kill switch changes (fast response)
    this.pollInterval = setInterval(() => this.refresh(), pollMs)
  }

  isKilled(switchKey: string): boolean {
    const cached = this.cache.get(switchKey)
    if (cached && cached.expiry > Date.now()) {
      return cached.value
    }
    // Fallback: if cache miss, assume NOT killed (fail open)
    return false
  }

  private async refresh(): <> {
     {
       switches =  ..()
       ( [key, value]  .(switches)) {
        ..(key, { value, : .() +  })
      }
    }  {
      
    }
  }

  ():  {
    (.)
  }
}


  () {
   (killSwitch.()) {
     res.().({
      : ,
      : ,
    })
  }
  
}

A/B Testing Integration

// Track experiment exposure and outcomes
interface ExperimentEvent {
  experimentKey: string
  variant: string
  userId: string
  timestamp: Date
  eventType: 'exposure' | 'conversion'
  metadata?: Record<string, unknown>
}

class ExperimentTracker {
  constructor(private analytics: AnalyticsClient) {}

  trackExposure(flagKey: string, variant: string, userId: string): void {
    this.analytics.track({
      experimentKey: flagKey,
      variant,
      userId,
      timestamp: new Date(),
      eventType: 'exposure',
    })
  }

  trackConversion(flagKey: string, userId: string, value?: number): void {
    this.analytics.({
      : flagKey,
      : featureFlags.(flagKey, userId),
      userId,
      :  (),
      : ,
      : { value },
    })
  }
}


 () {
   variant = featureFlags.(, user.)
  experimentTracker.(, variant, user.)

   (variant === ) {
     
  }
   
}

Flag Lifecycle and Cleanup

// Prevent flag debt: enforce expiration dates
async function auditFlags(): Promise<FlagAuditReport> {
  const flags = await flagStore.getAllFlags()
  const now = new Date()

  const report: FlagAuditReport = {
    total: flags.length,
    expired: [],
    noOwner: [],
    stale: [],
    permanent: [],
  }

  for (const flag of flags) {
    // Expired flags: should have been removed
    if (flag.expiresAt && flag.expiresAt < now) {
      report.expired.push(flag.key)
    }

    // No owner: nobody responsible for cleanup
    if (!flag.owner) {
      report.noOwner.push(flag.key)
    }

    // Stale: 100% rollout for > 2 weeks (just remove the flag)
    if (flag.type === 'percentage' && flag.percentage === 100) {
      const twoWeeksAgo = new Date(now.getTime() - 14 *  *  *  * )
       (flag. && flag. < twoWeeksAgo) {
        report..(flag.)
      }
    }

    
     (!flag. && !flag..() && !flag..()) {
      report..(flag.)
    }
  }

   report
}

Checklist

• Every release flag has an expiration date (max 3 months)
• Every flag has an owner (team or person)
• Consistent hashing for percentage rollout (same user, same result)
• Kill switches poll every 5-10 seconds (fast disable)
• A/B test exposure tracked before showing variant
• Flag audit runs weekly (detect expired, stale, ownerless flags)
• Remove flag code after full rollout (not just set to 100%)
• Default to safe value when flag service is unavailable (fail open/closed per flag)

Anti-Patterns

• Flags without expiration dates: accumulate as permanent technical debt
• Nested flag checks: if flagA && flagB && !flagC becomes unmaintainable
• Flag evaluation in hot loops: cache the result per request
• Not tracking experiment exposure: biased results, no statistical power
• Removing flag from config but leaving dead code branches
• Using flags for authorization (use proper RBAC/permissions instead)