@plyaz/types 1.5.1 → 1.5.3

package/dist/testing/features/feature-flags/types.d.ts

@@ -99,7 +99,7 @@ export interface SetupFeatureFlagModuleMocks {
     /** Mock logger instance */
     mockLogger: MockLogger;
     /** Mock HTTP exception constructor */
-    HttpException: Vitest.MockInstance;
+    HttpException: Vitest.Mock;
     /** HTTP status code constants */
     HttpStatus: Record<string, number>;
 }
@@ -250,25 +250,25 @@ export interface FeatureFlagScenarios<FeatureFlagKey extends string> {
  */
 export interface MockFeatureFlagProvider {
     /** Get a specific feature flag */
-    getFlag: Vitest.MockInstance;
+    getFlag: Vitest.Mock;
     /** Get all feature flags */
-    getAllFlags: Vitest.MockInstance;
+    getAllFlags: Vitest.Mock;
     /** Evaluate a feature flag */
-    evaluateFlag: Vitest.MockInstance;
+    evaluateFlag: Vitest.Mock;
     /** Check if a flag is enabled */
-    isEnabled: Vitest.MockInstance;
+    isEnabled: Vitest.Mock;
     /** Get a flag's value */
-    getValue: Vitest.MockInstance;
+    getValue: Vitest.Mock;
     /** Update a feature flag */
-    updateFlag: Vitest.MockInstance;
+    updateFlag: Vitest.Mock;
     /** Delete a feature flag */
-    deleteFlag: Vitest.MockInstance;
+    deleteFlag: Vitest.Mock;
     /** Refresh flag data */
-    refresh: Vitest.MockInstance;
+    refresh: Vitest.Mock;
     /** Subscribe to flag changes */
-    subscribe: Vitest.MockInstance;
+    subscribe: Vitest.Mock;
     /** Unsubscribe from flag changes */
-    unsubscribe: Vitest.MockInstance;
+    unsubscribe: Vitest.Mock;
 }
 /**
  * Mock feature flag repository interface for database operations testing
@@ -289,21 +289,21 @@ export interface MockFeatureFlagProvider {
  */
 export interface MockFeatureFlagRepository {
     /** Find a single flag by criteria */
-    find: Vitest.MockInstance;
+    find: Vitest.Mock;
     /** Find all flags */
-    findAll: Vitest.MockInstance;
+    findAll: Vitest.Mock;
     /** Create a new flag */
-    create: Vitest.MockInstance;
+    create: Vitest.Mock;
     /** Update an existing flag */
-    update: Vitest.MockInstance;
+    update: Vitest.Mock;
     /** Delete a flag */
-    delete: Vitest.MockInstance;
+    delete: Vitest.Mock;
     /** Save a flag */
-    save: Vitest.MockInstance;
+    save: Vitest.Mock;
     /** Check if a flag exists */
-    exists: Vitest.MockInstance;
+    exists: Vitest.Mock;
     /** Count total flags */
-    count: Vitest.MockInstance;
+    count: Vitest.Mock;
 }
 /**
  * Mock feature flag service interface for business logic testing
@@ -324,21 +324,21 @@ export interface MockFeatureFlagRepository {
  */
 export interface MockFeatureFlagService {
     /** Evaluate a single flag */
-    evaluate: Vitest.MockInstance;
+    evaluate: Vitest.Mock;
     /** Evaluate all flags */
-    evaluateAll: Vitest.MockInstance;
+    evaluateAll: Vitest.Mock;
     /** Check if flag is enabled */
-    isEnabled: Vitest.MockInstance;
+    isEnabled: Vitest.Mock;
     /** Get flag value */
-    getValue: Vitest.MockInstance;
+    getValue: Vitest.Mock;
     /** Get flag variation */
-    getVariation: Vitest.MockInstance;
+    getVariation: Vitest.Mock;
     /** Track flag usage */
-    track: Vitest.MockInstance;
+    track: Vitest.Mock;
     /** Refresh flag data */
-    refresh: Vitest.MockInstance;
+    refresh: Vitest.Mock;
     /** Clear cache */
-    invalidateCache: Vitest.MockInstance;
+    invalidateCache: Vitest.Mock;
 }
 /**
  * Mock feature flag evaluation engine interface for testing flag logic
@@ -356,15 +356,15 @@ export interface MockFeatureFlagService {
  */
 export interface MockFeatureFlagEngine {
     /** Evaluate flag with context */
-    evaluate: Vitest.MockInstance;
+    evaluate: Vitest.Mock;
     /** Evaluate conditions */
-    evaluateConditions: Vitest.MockInstance;
+    evaluateConditions: Vitest.Mock;
     /** Check rollout eligibility */
-    checkRollout: Vitest.MockInstance;
+    checkRollout: Vitest.Mock;
     /** Calculate variation */
-    calculateVariation: Vitest.MockInstance;
+    calculateVariation: Vitest.Mock;
     /** Get default value */
-    getDefaultValue: Vitest.MockInstance;
+    getDefaultValue: Vitest.Mock;
 }
 /**
  * Mock feature flag cache interface for testing caching behavior
@@ -385,21 +385,21 @@ export interface MockFeatureFlagEngine {
  */
 export interface MockFeatureFlagCache {
     /** Get cached value */
-    get: Vitest.MockInstance;
+    get: Vitest.Mock;
     /** Set cache value */
-    set: Vitest.MockInstance;
+    set: Vitest.Mock;
     /** Delete cached value */
-    delete: Vitest.MockInstance;
+    delete: Vitest.Mock;
     /** Clear all cache */
-    clear: Vitest.MockInstance;
+    clear: Vitest.Mock;
     /** Check if key exists */
-    has: Vitest.MockInstance;
+    has: Vitest.Mock;
     /** Get all cache keys */
-    keys: Vitest.MockInstance;
+    keys: Vitest.Mock;
     /** Get all cache values */
-    values: Vitest.MockInstance;
+    values: Vitest.Mock;
     /** Get cache size */
-    size: Vitest.MockInstance;
+    size: Vitest.Mock;
 }
 /**
  * Test context for feature flag testing with React components
@@ -1076,7 +1076,7 @@ export interface SubscriptionFeatureFlagTracker<FeatureFlagKey extends string> {
     /** Track a new subscription */
     track: (provider: IFeatureFlagProvider<FeatureFlagKey>, id?: string) => {
         id: string;
-        callback: Vitest.MockInstance;
+        callback: Vitest.Mock;
         unsubscribe: () => void;
     };
     /** Unsubscribe by ID */
@@ -1370,132 +1370,253 @@ export interface FileProviderTestScenario<FeatureFlagKey extends string> extends
     waitForFileChange: (ms?: number) => Promise<void>;
 }
 /**
- * Feature flag service interface for NestJS
- * @interface FeatureFlagService
+ * Feature flag service interface for NestJS applications.
+ * Provides comprehensive feature flag management including evaluation,
+ * CRUD operations, and provider integration.
+ *
+ * @example
+ * ```typescript
+ * const service: FeatureFlagService = {
+ *   logger: new Logger('FeatureFlagService'),
+ *   provider: launchDarklyProvider,
+ *   featureFlagRepository: repository,
+ *
+ *   // Lifecycle hooks
+ *   onModuleInit: async () => {
+ *     await service.initializeProvider();
+ *   },
+ *   onModuleDestroy: async () => {
+ *     await provider.close();
+ *   },
+ *
+ *   // Core operations
+ *   evaluateFlag: async (key, context) => {
+ *     return await provider.evaluate(key, context);
+ *   },
+ *   isEnabled: async (key, context) => {
+ *     const value = await service.evaluateFlag(key, context);
+ *     return Boolean(value);
+ *   }
+ * };
+ * ```
  */
 export interface FeatureFlagService {
-    /** Logger instance */
     logger: unknown;
-    /** Feature flag provider */
     provider: unknown;
-    /** Check if feature is enabled */
-    isEnabled: (key: string, context?: Record<string, unknown>) => Promise<boolean>;
-    /** Get feature value */
-    getValue: <T>(key: string, defaultValue: T, context?: Record<string, unknown>) => Promise<T>;
-    /** Get all features */
-    getAll: () => Promise<Record<string, unknown>>;
-    /** Refresh feature flags */
-    refresh: () => Promise<void>;
+    featureFlagRepository: unknown;
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    evaluateFlag(key: string, context?: unknown): Promise<unknown>;
+    isEnabled(key: string, context?: unknown): Promise<boolean>;
+    getValue(key: string, context?: unknown): Promise<unknown>;
+    getAllFlags(context?: unknown): Promise<unknown>;
+    createFlag(createData: unknown): Promise<unknown>;
+    updateFlag(key: string, updateData: unknown): Promise<unknown>;
+    deleteFlag(key: string): Promise<void>;
+    setOverride(key: string, value: unknown): Promise<void>;
+    removeOverride(key: string): Promise<void>;
+    getAllFeatureFlags(environment?: string): Promise<unknown[]>;
+    getFlagRules(key: string): Promise<unknown[]>;
+    refreshCache(): Promise<void>;
+    getHealthStatus(): Promise<unknown>;
+    initializeProvider(): Promise<void>;
+    getProvider(): unknown;
 }
 /**
- * Feature flag repository interface for NestJS
- * @interface FeatureFlagRepository
- * @typeParam FeatureFlagKey - Type of feature flag keys
+ * Feature flag repository interface for NestJS data persistence.
+ * Handles database operations for feature flags and rules.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const repository: FeatureFlagRepository<AppFlags> = {
+ *   logger: new Logger('FeatureFlagRepository'),
+ *
+ *   createFlag: async (data) => {
+ *     return await db.flags.create(data);
+ *   },
+ *   getFlag: async (key) => {
+ *     return await db.flags.findOne({ key });
+ *   },
+ *   updateFlag: async (key, data) => {
+ *     return await db.flags.update({ key }, data);
+ *   },
+ *   deleteFlag: async (key) => {
+ *     await db.flags.delete({ key });
+ *   },
+ *   getAllFlags: async (environment) => {
+ *     return environment
+ *       ? await db.flags.find({ environment })
+ *       : await db.flags.find();
+ *   }
+ * };
+ * ```
  */
 export interface FeatureFlagRepository<FeatureFlagKey extends string> {
-    /** Logger instance */
     logger: unknown;
-    /** Find feature flag by key */
-    findByKey: (key: FeatureFlagKey) => Promise<unknown>;
-    /** Create new feature flag */
-    create: (key: FeatureFlagKey, data: unknown) => Promise<unknown>;
-    /** Update feature flag */
-    update: (key: FeatureFlagKey, data: unknown) => Promise<unknown>;
-    /** Delete feature flag */
-    delete: (key: FeatureFlagKey) => Promise<void>;
-    /** Find all feature flags */
-    findAll: () => Promise<Array<{
-        key: FeatureFlagKey;
-        data: unknown;
-    }>>;
+    createFlag(createData: unknown): Promise<unknown>;
+    updateFlag(key: FeatureFlagKey, updateData: unknown): Promise<unknown>;
+    deleteFlag(key: FeatureFlagKey): Promise<void>;
+    getAllFlags(environment?: string): Promise<unknown[]>;
+    getFlagRules(key: FeatureFlagKey): Promise<unknown[]>;
+    getFlag(key: FeatureFlagKey): Promise<unknown>;
+    createRule(rule: unknown): Promise<unknown>;
+    updateRule(ruleId: string, updateData: unknown): Promise<unknown>;
+    deleteRule(ruleId: string): Promise<void>;
+    getFlagByKey(key: FeatureFlagKey): Promise<unknown>;
+    getAllRules(): Promise<unknown[]>;
+    createSampleFlags(): Promise<void>;
+    filterFlagsByEnvironment(flags: unknown[], environment: string): unknown[];
+    inferFlagType(value: unknown): string;
 }
 /**
- * Rollout configuration for testing
- * @interface RolloutConfig
- * @typeParam T - Type of feature flag keys
+ * Configuration for gradual feature rollout testing.
+ * Defines parameters for progressive deployment of features.
+ *
+ * @template T - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const rolloutConfig: RolloutConfig<'newFeature'> = {
+ *   flagKey: 'newFeature',
+ *   startPercentage: 0,
+ *   endPercentage: 100,
+ *   duration: 7 * 24 * 60 * 60 * 1000, // 1 week
+ *   userBucketingKey: 'userId'
+ * };
+ * ```
  */
 export interface RolloutConfig<T extends string> {
-    /** Feature flag key */
     flagKey: T;
-    /** Starting rollout percentage */
     startPercentage: number;
-    /** Ending rollout percentage */
     endPercentage: number;
-    /** Duration of rollout */
     duration: number;
+    userBucketingKey?: string;
 }
 /**
- * Rollout scenario for testing
- * @interface RolloutScenario
- * @typeParam T - Type of feature flag keys
+ * Rollout scenario for simulating gradual feature deployment.
+ * Provides methods to test time-based rollout strategies.
+ *
+ * @template T - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const scenario: RolloutScenario<'betaFeature'> = {
+ *   config: rolloutConfig,
+ *   getCurrentPercentage: () => {
+ *     // Calculate based on elapsed time
+ *     return Math.min(100, elapsedTime / duration * 100);
+ *   },
+ *   advanceTime: (ms) => {
+ *     currentTime += ms;
+ *   },
+ *   isUserEnabled: (userId) => {
+ *     const hash = hashUserId(userId);
+ *     return hash % 100 < getCurrentPercentage();
+ *   },
+ *   reset: () => {
+ *     currentTime = 0;
+ *   }
+ * };
+ * ```
  */
 export interface RolloutScenario<T extends string> {
-    /** Rollout configuration */
     config: RolloutConfig<T>;
-    /** Get current percentage */
     getCurrentPercentage: () => number;
-    /** Update percentage */
-    updatePercentage: (percentage: number) => void;
-    /** Check if flag is enabled for user */
-    isEnabledForUser: (userId: string) => boolean;
+    advanceTime: (ms: number) => void;
+    isUserEnabled: (userId: string) => boolean;
+    reset: () => void;
 }
 /**
- * A/B test configuration
- * @interface ABTestConfig
- * @typeParam T - Type of feature flag keys
+ * Configuration for A/B testing experiments.
+ * Defines variants, traffic allocation, and segmentation rules.
+ *
+ * @template T - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const abTestConfig: ABTestConfig<'checkoutFlow'> = {
+ *   flagKey: 'checkoutFlow',
+ *   variants: {
+ *     control: 'oldCheckout',
+ *     treatment: 'newCheckout'
+ *   },
+ *   trafficAllocation: {
+ *     control: 50,
+ *     treatment: 50
+ *   },
+ *   userBucketingKey: 'userId',
+ *   segmentationRules: [
+ *     {
+ *       attribute: 'country',
+ *       operator: 'equals',
+ *       value: 'US',
+ *       variant: 'treatment'
+ *     }
+ *   ]
+ * };
+ * ```
  */
 export interface ABTestConfig<T extends string> {
-    /** Feature flag key */
     flagKey: T;
-    /** Test variants */
     variants: {
-        /** Variant A configuration */
-        A: {
-            /** Variant percentage */
-            percentage: number;
-            /** Variant value */
-            value: FeatureFlagValue;
-        };
-        /** Variant B configuration */
-        B: {
-            /** Variant percentage */
-            percentage: number;
-            /** Variant value */
-            value: FeatureFlagValue;
-        };
+        control: FeatureFlagValue;
+        treatment: FeatureFlagValue;
     };
-    /** Test duration */
-    duration?: number;
-    /** Target audience */
-    audience?: {
-        /** Include criteria */
-        include?: string[];
-        /** Exclude criteria */
-        exclude?: string[];
+    trafficAllocation: {
+        control: number;
+        treatment: number;
     };
+    userBucketingKey?: string;
+    segmentationRules?: Array<{
+        attribute: string;
+        operator: 'equals' | 'contains' | 'in';
+        value: unknown;
+        variant: 'control' | 'treatment';
+    }>;
 }
 /**
- * A/B test scenario for testing
- * @interface ABTestScenario
- * @typeParam T - Type of feature flag keys
+ * A/B test scenario for simulating split testing experiments.
+ * Provides methods to determine user variants and analyze traffic distribution.
+ *
+ * @template T - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const abTest: CreateABTestScenario<'pricing'> = {
+ *   config: abTestConfig,
+ *   getVariantForUser: (userId, attributes) => {
+ *     // Check segmentation rules first
+ *     for (const rule of config.segmentationRules || []) {
+ *       if (evaluateRule(rule, attributes)) {
+ *         return config.variants[rule.variant];
+ *       }
+ *     }
+ *     // Default to traffic allocation
+ *     const hash = hashUserId(userId);
+ *     return hash % 100 < config.trafficAllocation.control
+ *       ? config.variants.control
+ *       : config.variants.treatment;
+ *   },
+ *   getTrafficDistribution: () => ({
+ *     control: config.trafficAllocation.control,
+ *     treatment: config.trafficAllocation.treatment
+ *   }),
+ *   reset: () => {
+ *     // Reset any cached results
+ *   }
+ * };
+ * ```
  */
 export interface CreateABTestScenario<T extends string> {
     /** A/B test configuration */
     config: ABTestConfig<T>;
     /** Get variant for user */
     getVariantForUser: (userId: string, attributes?: Record<string, unknown>) => FeatureFlagValue;
-    /** Get variant statistics */
-    getVariantStats: () => {
-        /** Variant A statistics */
-        A: {
-            count: number;
-            percentage: number;
-        };
-        /** Variant B statistics */
-        B: {
-            count: number;
-            percentage: number;
-        };
+    getTrafficDistribution: () => {
+        control: number;
+        treatment: number;
     };
     /** Reset test state */
     reset: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",