nest-feature-flags 1.0.0

package/src/interfaces/feature-flag-options.interface.ts

@@ -0,0 +1,25 @@
+import { ModuleMetadata } from '@nestjs/common';
+import { FeatureFlag } from './feature-flag.interface';
+
+/**
+ * Module configuration options
+ */
+export interface FeatureFlagsModuleOptions {
+  /**
+   * Feature flag definitions
+   */
+  flags: Record<string, FeatureFlag>;
+
+  /**
+   * Default value when flag is not found
+   */
+  defaultValue?: boolean;
+}
+
+/**
+ * Async module options
+ */
+export interface FeatureFlagsModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+  useFactory?: (...args: any[]) => Promise<FeatureFlagsModuleOptions> | FeatureFlagsModuleOptions;
+  inject?: any[];
+}

package/src/interfaces/feature-flag.interface.ts

@@ -0,0 +1,84 @@
+/**
+ * Feature flag configuration
+ */
+export interface FeatureFlag {
+  /**
+   * Master switch - feature is enabled
+   */
+  enabled: boolean;
+
+  /**
+   * Percentage of users who should see this feature (0-100)
+   */
+  percentage?: number;
+
+  /**
+   * Specific user IDs who should see this feature
+   */
+  userIds?: string[];
+
+  /**
+   * User groups who should see this feature
+   */
+  groups?: string[];
+
+  /**
+   * Date when feature becomes active
+   */
+  startDate?: Date;
+
+  /**
+   * Date when feature becomes inactive
+   */
+  endDate?: Date;
+
+  /**
+   * Feature description
+   */
+  description?: string;
+}
+
+/**
+ * Context for evaluating feature flags
+ */
+export interface FeatureFlagContext {
+  /**
+   * User ID for targeting
+   */
+  userId?: string;
+
+  /**
+   * User groups for targeting
+   */
+  groups?: string[];
+
+  /**
+   * Additional custom attributes
+   */
+  attributes?: Record<string, any>;
+}
+
+/**
+ * Result of feature flag evaluation
+ */
+export interface FeatureFlagResult {
+  /**
+   * Flag key
+   */
+  key: string;
+
+  /**
+   * Whether feature is enabled for this context
+   */
+  enabled: boolean;
+
+  /**
+   * Reason for the decision
+   */
+  reason: string;
+
+  /**
+   * Variant (for A/B testing)
+   */
+  variant?: string;
+}

package/src/services/feature-flag.service.spec.ts

@@ -0,0 +1,51 @@
+import { Test } from '@nestjs/testing';
+import { FeatureFlagService, OPTIONS_TOKEN } from './feature-flag.service';
+
+describe('FeatureFlagService', () => {
+  let service: FeatureFlagService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        FeatureFlagService,
+        {
+          provide: OPTIONS_TOKEN,
+          useValue: {
+            flags: {
+              'enabled-flag': { enabled: true },
+              'disabled-flag': { enabled: false },
+              'percentage-flag': { enabled: true, percentage: 50 },
+              'user-targeted': { enabled: true, userIds: ['user1'] },
+            },
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<FeatureFlagService>(FeatureFlagService);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  it('should return true for enabled flag', async () => {
+    const result = await service.isEnabled('enabled-flag');
+    expect(result).toBe(true);
+  });
+
+  it('should return false for disabled flag', async () => {
+    const result = await service.isEnabled('disabled-flag');
+    expect(result).toBe(false);
+  });
+
+  it('should target specific users', async () => {
+    const result = await service.isEnabled('user-targeted', { userId: 'user1' });
+    expect(result).toBe(true);
+  });
+
+  it('should handle percentage rollout', async () => {
+    const result = await service.isEnabled('percentage-flag', { userId: 'test' });
+    expect(typeof result).toBe('boolean');
+  });
+});

package/src/services/feature-flag.service.ts

@@ -0,0 +1,99 @@
+import { Injectable, Inject } from '@nestjs/common';
+import { FeatureFlag, FeatureFlagContext, FeatureFlagResult } from '../interfaces/feature-flag.interface';
+import { FeatureFlagsModuleOptions } from '../interfaces/feature-flag-options.interface';
+
+const OPTIONS_TOKEN = 'FEATURE_FLAGS_OPTIONS';
+
+@Injectable()
+export class FeatureFlagService {
+  constructor(
+    @Inject(OPTIONS_TOKEN)
+    private readonly options: FeatureFlagsModuleOptions,
+  ) {}
+
+  /**
+   * Check if a feature is enabled
+   */
+  async isEnabled(key: string, context?: FeatureFlagContext): Promise<boolean> {
+    const result = await this.evaluate(key, context);
+    return result.enabled;
+  }
+
+  /**
+   * Evaluate a feature flag
+   */
+  async evaluate(key: string, context?: FeatureFlagContext): Promise<FeatureFlagResult> {
+    const flag = this.options.flags[key];
+
+    if (!flag) {
+      return {
+        key,
+        enabled: this.options.defaultValue ?? false,
+        reason: 'Flag not found',
+      };
+    }
+
+    // Check master switch
+    if (!flag.enabled) {
+      return { key, enabled: false, reason: 'Flag disabled' };
+    }
+
+    // Check date range
+    const now = new Date();
+    if (flag.startDate && now < flag.startDate) {
+      return { key, enabled: false, reason: 'Not started yet' };
+    }
+    if (flag.endDate && now > flag.endDate) {
+      return { key, enabled: false, reason: 'Expired' };
+    }
+
+    // Check user targeting
+    if (context?.userId && flag.userIds?.includes(context.userId)) {
+      return { key, enabled: true, reason: 'User targeted' };
+    }
+
+    // Check group targeting
+    if (context?.groups && flag.groups) {
+      const hasGroup = context.groups.some(g => flag.groups!.includes(g));
+      if (hasGroup) {
+        return { key, enabled: true, reason: 'Group targeted' };
+      }
+    }
+
+    // Check percentage rollout
+    if (flag.percentage !== undefined) {
+      const hash = this.hashUserId(context?.userId || 'anonymous');
+      const userPercentage = hash % 100;
+      const enabled = userPercentage < flag.percentage;
+      return {
+        key,
+        enabled,
+        reason: enabled ? 'In percentage rollout' : 'Not in percentage rollout',
+      };
+    }
+
+    return { key, enabled: true, reason: 'Fully enabled' };
+  }
+
+  /**
+   * Get all flags
+   */
+  getAllFlags(): Record<string, FeatureFlag> {
+    return this.options.flags;
+  }
+
+  /**
+   * Simple hash function for consistent percentage rollout
+   */
+  private hashUserId(userId: string): number {
+    let hash = 0;
+    for (let i = 0; i < userId.length; i++) {
+      const char = userId.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash);
+  }
+}
+
+export { OPTIONS_TOKEN };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2021",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "strictBindCallApply": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}