Feature Flag Documentation

This documentation explains the features and usage of Feature Flag Module: Located at src/modules/feature-flag

Overview

Feature flag module provides dynamic feature management for controlling application functionality. Supports gradual rollouts, A/B testing, and metadata-based feature configuration with caching for optimal performance.

Related Documents

• Cache Documentation

Table of Contents

• Related Documents
• Features
• Flow
• Usage
  • With Decorators
  • With Service
• Metadata
• Rollout Percentage
• Caching
• Restrictions

Features

Feature flags provided in src/migration/feature-flag.ts:

Flow

The FeatureFlagGuard validates feature flag status before allowing route access.

Usage

With Decorators

Important: @FeatureFlagProtected() does NOT provide authentication. Apply authentication guards separately if required.

Use @FeatureFlagProtected() decorator to protect routes:

@Controller('auth')
export class AuthController {
  // Simple feature check
  @FeatureFlagProtected('loginWithGoogle')
  @Post('google')
  async loginWithGoogle() {
    // Route accessible only if loginWithGoogle is enabled
  }
 
  // Nested metadata check
  @FeatureFlagProtected('changePassword.forgotAllowed')
  @Post('forgot-password')
  async forgotPassword() {
    // Route accessible only if changePassword is enabled 
    // AND forgotAllowed metadata is true
  }
}

With Service

@Injectable()
export class YourService {
  constructor(
    private readonly featureFlagService: FeatureFlagService
  ) {}
 
  async example() {
    // Get feature flag with cache
    const flag = await this.featureFlagService.findOneByKeyAndCache('loginWithGoogle');
    
    // Get metadata only
    const metadata = await this.featureFlagService.findOneMetadataByKeyAndCache('changePassword');
  }
}

Metadata

Metadata provides granular control within a single feature flag:

// Feature flag with metadata
{
  key: 'changePassword',
  isEnable: true,
  metadata: {
    forgotAllowed: true,  // Can be toggled independently
    resetAllowed: false
  }
}

Constraints:

• No nested objects allowed
• Supports types: boolean, number, string
• Metadata keys cannot be added/removed (schema consistency)
• Only values can be modified

Nested Key Access:

// Check both feature AND metadata
@FeatureFlagProtected('changePassword.forgotAllowed')

When using nested keys, metadata value must be boolean.

Rollout Percentage

Controls gradual feature deployment using deterministic hashing:

{
  key: 'newFeature',
  rolloutPercent: 30  // 30% of users get access
}

How it works:

1. User identifier (userId) is hashed using MD5
2. Hash converted to percentage (0-99)
3. Compared against rolloutPercent
4. Same user always gets same result (deterministic)

Use cases:

• A/B testing
• Gradual rollouts
• Canary deployments

Caching

Feature flags are cached for performance. Configuration in src/configs/feature-flag.config.ts:

{
  cachePrefixKey: 'FeatureFlag',
  cacheTtlMs: 3600  // 1 hour
}

Cache operations:

• Automatic cache on first read
• Cache invalidation on updates
• Key format: FeatureFlag:{key}

See Cache Documentation for cache system details.

Restrictions

• Feature flags cannot be added via admin API
• Feature flags cannot be deleted
• Metadata keys cannot be modified (add/remove)
• Only values can be updated: isEnable, rolloutPercent, metadata values