@venturialstd/feature-flag

Business-agnostic Feature Flags module for Venturial. Provides evaluation engine, persistence, and Nest integration (guards/decorators). Applications define which flags to create and where to check them.

Use cases

• Gradual rollout: Enable a flow for a percentage of users, then increase or enable for everyone.
• Kill switch: Disable a feature in production without redeploying.
• Internal / beta: Expose functionality only to specific users or roles.
• A/B or experimentation: Drive variant A vs B by user id or segment.
• Permission-like gating: Restrict access via a flag (e.g. premium-reports).

Installation

npm install @venturialstd/feature-flag

Setup

1. Register the entity in TypeORM (e.g. include node_modules/@venturialstd/feature-flag/dist/**/*.entity.js in your entities).
2. Run the migration to create the feature_flag table (see test/migrations for reference).
3. Import the module in your app:

import { FeatureFlagModule } from '@venturialstd/feature-flag';

@Module({
  imports: [FeatureFlagModule.forRoot({ cacheTtlSeconds: 60 })],
})
export class AppModule {}

Usage

Evaluate in code

constructor(private readonly featureFlagService: FeatureFlagService) {}

async someMethod() {
  const enabled = await this.featureFlagService.isEnabled('new-onboarding-v2', {
    userId: user.id,
    roles: ['ADMIN', 'BETA_TESTER'],
  });
  if (enabled) {
    // new flow
  }
}

Guard routes

import { RequireFeature, RequireFeatureGuard } from '@venturialstd/feature-flag';

@RequireFeature('new-dashboard')
@UseGuards(JwtAuthGuard, UserGuard, RequireFeatureGuard)
@Get()
getDashboard() { ... }

Context (userId, roles) is taken from the request (e.g. request.user after JWT + UserGuard).

CRUD

• featureFlagService.getFlag(key), getFlagById(id), listFlags()
• featureFlagService.create(dto), update(id, dto), delete(id)

Expose these via your own admin controller and protect with ACL (e.g. feature_flag.manage).

Entity

• id (uuid), key (string, unique), name, description, enabled, targetingRules (jsonb), metadata (jsonb), createdAt, updatedAt

Targeting rules

• scope: everyone (no rules) or by_rules.
• userIds: List of user IDs that get the feature (allowlist).
• roles: List of role names; user with any of these roles gets the feature.
• percentageRollout: 0–100; a stable subset of users (by hash of userId) get the feature.

When enabled is false, the flag evaluates to false for everyone. When enabled with no rules (or scope everyone), it evaluates to true for everyone.