nest-feature-flags 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [1.1.0] - 2026-01-31
+
+### Added
+- Comprehensive test suite with guard and module tests
+- Docker support with multi-stage builds
+- GitHub Actions CI/CD pipeline
+- Contributing guidelines
+- npmignore configuration
+
+### Improved
+- Enhanced documentation
+- Better test coverage
+
+## [1.0.0] - 2026-01-31
+
+### Added
+- Initial release
+- Feature flag service
+- Percentage-based rollouts
+- User targeting
+- Group targeting
+- Date-based activation

package/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing to nest-feature-flags
+
+Thank you for contributing!
+
+## Development Setup
+
+```bash
+git clone https://github.com/syeedalireza/nest-feature-flags.git
+cd nest-feature-flags
+npm install
+npm test
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create feature branch
+3. Write tests
+4. Submit PR
+
+## Code Style
+
+- Follow ESLint/Prettier
+- Write tests for new features
+- Update documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nest-feature-flags",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Professional feature flag management system for NestJS with A/B testing, gradual rollouts, user targeting, and real-time updates",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/.eslintrc.js

@@ -1,25 +0,0 @@
-module.exports = {
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    project: 'tsconfig.json',
-    tsconfigRootDir: __dirname,
-    sourceType: 'module',
-  },
-  plugins: ['@typescript-eslint/eslint-plugin'],
-  extends: [
-    'plugin:@typescript-eslint/recommended',
-    'plugin:prettier/recommended',
-  ],
-  root: true,
-  env: {
-    node: true,
-    jest: true,
-  },
-  ignorePatterns: ['.eslintrc.js'],
-  rules: {
-    '@typescript-eslint/interface-name-prefix': 'off',
-    '@typescript-eslint/explicit-function-return-type': 'off',
-    '@typescript-eslint/explicit-module-boundary-types': 'off',
-    '@typescript-eslint/no-explicit-any': 'warn',
-  },
-};

package/.prettierrc

@@ -1,8 +0,0 @@
-{
-  "singleQuote": true,
-  "trailingComma": "all",
-  "printWidth": 100,
-  "tabWidth": 2,
-  "semi": true,
-  "endOfLine": "lf"
-}

package/jest.config.js

@@ -1,23 +0,0 @@
-module.exports = {
-  moduleFileExtensions: ['js', 'json', 'ts'],
-  rootDir: 'src',
-  testRegex: '.*\\.spec\\.ts$',
-  transform: {
-    '^.+\\.(t|j)s$': 'ts-jest',
-  },
-  collectCoverageFrom: [
-    '**/*.(t|j)s',
-    '!**/*.spec.ts',
-    '!**/index.ts',
-  ],
-  coverageDirectory: '../coverage',
-  testEnvironment: 'node',
-  coverageThreshold: {
-    global: {
-      branches: 55,
-      functions: 65,
-      lines: 65,
-      statements: 65,
-    },
-  },
-};

package/src/decorators/feature-flag.decorator.ts

@@ -1,8 +0,0 @@
-import { SetMetadata } from '@nestjs/common';
-
-export const FEATURE_FLAG_KEY = 'feature_flag_key';
-
-/**
- * Decorator to require a feature flag
- */
-export const RequireFeature = (flagKey: string) => SetMetadata(FEATURE_FLAG_KEY, flagKey);

package/src/feature-flags.module.ts

@@ -1,42 +0,0 @@
-import { Module, DynamicModule, Global } from '@nestjs/common';
-import { FeatureFlagsModuleOptions, FeatureFlagsModuleAsyncOptions } from './interfaces/feature-flag-options.interface';
-import { FeatureFlagService, OPTIONS_TOKEN } from './services/feature-flag.service';
-import { FeatureFlagGuard } from './guards/feature-flag.guard';
-
-@Global()
-@Module({})
-export class FeatureFlagsModule {
-  static forRoot(options: FeatureFlagsModuleOptions): DynamicModule {
-    return {
-      module: FeatureFlagsModule,
-      providers: [
-        {
-          provide: OPTIONS_TOKEN,
-          useValue: options,
-        },
-        FeatureFlagService,
-        FeatureFlagGuard,
-      ],
-      exports: [FeatureFlagService, FeatureFlagGuard],
-      global: true,
-    };
-  }
-
-  static forRootAsync(options: FeatureFlagsModuleAsyncOptions): DynamicModule {
-    return {
-      module: FeatureFlagsModule,
-      imports: options.imports || [],
-      providers: [
-        {
-          provide: OPTIONS_TOKEN,
-          useFactory: options.useFactory!,
-          inject: options.inject || [],
-        },
-        FeatureFlagService,
-        FeatureFlagGuard,
-      ],
-      exports: [FeatureFlagService, FeatureFlagGuard],
-      global: true,
-    };
-  }
-}

package/src/guards/feature-flag.guard.ts

@@ -1,35 +0,0 @@
-import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
-import { FeatureFlagService } from '../services/feature-flag.service';
-import { FEATURE_FLAG_KEY } from '../decorators/feature-flag.decorator';
-
-@Injectable()
-export class FeatureFlagGuard implements CanActivate {
-  constructor(
-    private readonly reflector: Reflector,
-    private readonly featureFlagService: FeatureFlagService,
-  ) {}
-
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const flagKey = this.reflector.get<string>(FEATURE_FLAG_KEY, context.getHandler());
-
-    if (!flagKey) {
-      return true;
-    }
-
-    const request = context.switchToHttp().getRequest();
-    const userId = request.user?.id || request.userId;
-    const groups = request.user?.groups || [];
-
-    const enabled = await this.featureFlagService.isEnabled(flagKey, {
-      userId,
-      groups,
-    });
-
-    if (!enabled) {
-      throw new ForbiddenException(`Feature '${flagKey}' is not available`);
-    }
-
-    return true;
-  }
-}

package/src/index.ts

@@ -1,13 +0,0 @@
-// Module
-export * from './feature-flags.module';
-
-// Service
-export * from './services/feature-flag.service';
-
-// Guards & Decorators
-export * from './guards/feature-flag.guard';
-export * from './decorators/feature-flag.decorator';
-
-// Interfaces
-export * from './interfaces/feature-flag.interface';
-export * from './interfaces/feature-flag-options.interface';

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

@@ -1,25 +0,0 @@
-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

@@ -1,84 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-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

@@ -1,99 +0,0 @@
-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

@@ -1,25 +0,0 @@
-{
-  "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"]
-}