feature-flag-patterns

# Feature Flag Patterns Feature flag strategies for safe deployments, experimentation, and operational control. ## Flag Types and Structure ```typescript 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 ```typescript 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 private consistentHash(flagKey: string, userId: string): number { const input = `${flagKey}:${userId}` let hash = 0 for (let i = 0; i < input.length; i++) { const char = input.charCodeAt(i) hash = ((hash << 5) - hash) + char hash = hash & hash // Convert to 32-bit integer } return Math.abs(hash) % 100 // 0-99 } // Multi-variant for A/B/C testing getVariant(flagKey: string, userId: string): string { const flag = this.store.getFlag(flagKey) if (!flag?.enabled || !flag.variants) return 'control' const hash = this.consistentHash(flagKey, userId) let cumulative = 0 for (const variant of flag.variants) { cumulative += variant.weight if (hash < cumulative) return variant.name } return 'control' } // Segment-based targeting private isInSegment(userId: string, segments: Segment[]): boolean { const user = this.store.getUser(userId) return segments.some(segment => { switch (segment.type) { case 'user_list': return segment.userIds.includes(userId) case 'attribute': return user?.[segment.attribute] === segment.value case 'percentage': return this.consistentHash(segment.id, userId) < segment.value } }) } } ``` ## Kill Switch Pattern ```typescript // 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(): Promise<void> { try { const switches = await this.store.getKillSwitches() for (const [key, value] of Object.entries(switches)) { this.cache.set(key, { value, expiry: Date.now() + 10_000 }) } } catch { // On error, extend existing cache TTL (don't flip switches on failure) } } destroy(): void { clearInterval(this.pollInterval) } } // Usage in request handler async function handleCheckout(req: Request, res: Response) { if (killSwitch.isKilled('checkout-disabled')) { return res.status(503).json({ error: 'Checkout temporarily unavailable', retryAfter: 300, }) } // ... normal checkout logic } ``` ## A/B Testing Integration ```typescript // 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.track({ experimentKey: flagKey, variant: featureFlags.getVariant(flagKey, userId), userId, timestamp: new Date(), eventType: 'conversion', metadata: { value }, }) } } // Usage: checkout experiment function CheckoutPage({ user }: { user: User }) { const variant = featureFlags.getVariant('checkout-redesign', user.id) experimentTracker.trackExposure('checkout-redesign', variant, user.id) if (variant === 'new') { return <NewCheckout onComplete={() => { experimentTracker.trackConversion('checkout-redesign', user.id) }} /> } return <OldCheckout onComplete={() => { experimentTracker.trackConversion('checkout-redesign', user.id) }} /> } ``` ## Flag Lifecycle and Cleanup ```typescript // 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 * 24 * 60 * 60 * 1000) if (flag.lastModified && flag.lastModified < twoWeeksAgo) { report.stale.push(flag.key) } } // Permanent flags without ops/permission tag if (!flag.expiresAt && !flag.tags.includes('ops') && !flag.tags.includes('permission')) { report.permanent.push(flag.key) } } return report } // Run weekly: flag cleanup report // Slack alert for expired/stale flags ``` ## 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)