@plyaz/types 1.3.2 → 1.3.3

package/dist/features/feature-flag/types.d.ts

@@ -0,0 +1,491 @@
+/**
+ * Feature Flags Domain Types
+ *
+ * Core type definitions for the feature flags domain.
+ *
+ * @fileoverview Feature flags domain type definitions
+ * @version 1.0.0
+ */
+import type * as React from 'react';
+/**
+ * Possible values that a feature flag can hold.
+ * Supports primitive types and JSON objects for complex configurations.
+ */
+export type FeatureFlagValue = boolean | string | number | Record<string, unknown>;
+/**
+ * Core feature flag definition interface.
+ * Represents a complete feature flag with all its metadata and configuration.
+ */
+export interface FeatureFlag<FeatureFlagKey extends string> {
+    /** The unique identifier for this flag */
+    key: FeatureFlagKey;
+    /** Human-readable name for the flag */
+    name: string;
+    /** Detailed description of what this flag controls */
+    description: string;
+    /** Whether this flag is currently active */
+    isEnabled: boolean;
+    /** The value returned when this flag is evaluated */
+    value: FeatureFlagValue;
+    /** The data type of the flag value */
+    type: 'boolean' | 'string' | 'number' | 'json';
+    /** Which environment(s) this flag applies to */
+    environment: 'development' | 'staging' | 'production' | 'all';
+    /** Percentage of users who should receive this flag (0-100) */
+    rolloutPercentage?: number;
+    /** Timestamp when this flag was created */
+    createdAt: Date;
+    /** Timestamp when this flag was last updated */
+    updatedAt: Date;
+    /** Email or ID of the user who created this flag */
+    createdBy: string;
+    /** Email or ID of the user who last updated this flag */
+    updatedBy: string;
+}
+/**
+ * Feature flag rule for advanced targeting and conditional logic.
+ */
+export interface FeatureFlagRule<FeatureFlagKey extends string> {
+    /** Unique identifier for this rule */
+    id: string;
+    /** The feature flag this rule applies to */
+    flagKey: FeatureFlagKey;
+    /** Human-readable name for this rule */
+    name: string;
+    /** Array of conditions that must all be met for this rule to apply */
+    conditions: FeatureFlagCondition[];
+    /** The value to return if this rule matches */
+    value: FeatureFlagValue;
+    /** Percentage of matching users who should receive this value (0-100) */
+    rolloutPercentage?: number;
+    /** Priority for rule evaluation (higher numbers = higher priority) */
+    priority: number;
+    /** Whether this rule is currently active */
+    isEnabled: boolean;
+}
+/**
+ * Individual condition for feature flag rule evaluation.
+ */
+export interface FeatureFlagCondition {
+    /** The context field to evaluate */
+    field: 'userId' | 'userEmail' | 'userRole' | 'country' | 'platform' | 'version' | 'environment' | 'custom';
+    /** The comparison operator to use */
+    operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'greater_than' | 'less_than';
+    /** The value(s) to compare against */
+    value: string | number | string[] | number[];
+}
+/**
+ * Context information used for feature flag evaluation.
+ */
+export interface FeatureFlagContext {
+    /** Unique identifier for the user */
+    userId?: string;
+    /** User's email address */
+    userEmail?: string;
+    /** User's role or permission level */
+    userRole?: string;
+    /** User's country code (ISO 3166-1 alpha-2) */
+    country?: string;
+    /** Platform the user is accessing from */
+    platform?: 'web' | 'mobile' | 'desktop';
+    /** Application version */
+    version?: string;
+    /** Custom context data for advanced targeting */
+    custom?: Record<string, unknown>;
+    /** Current environment */
+    environment: 'development' | 'staging' | 'production';
+}
+/**
+ * Result of a feature flag evaluation.
+ */
+export interface FeatureFlagEvaluation<FeatureFlagKey extends string> {
+    /** The feature flag key that was evaluated */
+    flagKey: FeatureFlagKey;
+    /** The resolved value for this flag */
+    value: FeatureFlagValue;
+    /** Whether the flag is considered enabled (truthy value) */
+    isEnabled: boolean;
+    /** Explanation of how this value was determined */
+    reason: 'default' | 'rule_match' | 'rollout' | 'override' | 'disabled';
+    /** Source of the evaluation result */
+    source?: 'default' | 'override' | 'rule' | 'rollout';
+    /** ID of the rule that matched (if reason is 'rule_match') */
+    ruleId?: string;
+    /** Timestamp when this evaluation occurred */
+    evaluatedAt: Date;
+}
+/**
+ * Configuration options for the feature flag system.
+ */
+export interface FeatureFlagConfig<FeatureFlagKey extends string> {
+    /** The storage provider to use for flag data */
+    provider: 'database' | 'redis' | 'memory' | 'api' | 'file';
+    /** Whether to enable caching of flag evaluations */
+    isCacheEnabled: boolean;
+    /** Cache time-to-live in seconds */
+    cacheTtl: number;
+    /** How often to refresh flag data in seconds (0 = no auto-refresh) */
+    refreshInterval: number;
+    /** Whether to fall back to default values on errors */
+    shouldFallbackToDefaults: boolean;
+    /** Whether to enable debug logging */
+    isLoggingEnabled: boolean;
+    /** API endpoint URL (required if provider is 'api') */
+    apiEndpoint?: string;
+    /** API authentication key (required if provider is 'api') */
+    apiKey?: string;
+    /** Database configuration (required if provider is 'database') */
+    databaseConfig?: {
+        connectionString: string;
+        tableName: string;
+    };
+    /** Redis configuration (required if provider is 'redis') */
+    redisConfig?: {
+        url: string;
+        keyPrefix: string;
+    };
+    /** File configuration (required if provider is 'file') */
+    fileConfig?: {
+        filePath: string;
+        format: 'json' | 'yaml';
+        shouldWatchForChanges: boolean;
+    };
+    /** Memory provider rules (optional for memory provider) */
+    memoryRules?: FeatureFlagRule<FeatureFlagKey>[];
+}
+/**
+ * React Hook Options for Feature Flags
+ */
+export interface UseFeatureFlagOptions {
+    /** Evaluation context for targeting */
+    context?: FeatureFlagContext;
+    /** Whether to automatically refresh on provider updates */
+    isAutoRefresh?: boolean;
+    /** Default value to use while loading or on error */
+    defaultValue?: FeatureFlagValue;
+    /** Whether to suspend on initial load (for Suspense) */
+    isSuspense?: boolean;
+}
+/**
+ * Internal state for feature flag evaluation in React hooks.
+ */
+export interface FeatureFlagState<FeatureFlagKey extends string, T extends FeatureFlagValue = FeatureFlagValue> {
+    value: T;
+    isLoading: boolean;
+    error: Error | null;
+    evaluation: FeatureFlagEvaluation<FeatureFlagKey> | null;
+}
+/**
+ * Context value interface for React feature flag provider.
+ */
+export interface FeatureFlagContextValue<FeatureFlagKey extends string> {
+    /** The feature flag provider instance */
+    provider: FeatureFlagProvider<FeatureFlagKey>;
+    /** Whether the provider is initialized */
+    isInitialized: boolean;
+    /** Whether the provider is currently loading */
+    isLoading: boolean;
+    /** Any error that occurred during initialization */
+    error: Error | null;
+    /** When the provider was last updated */
+    lastUpdated: Date | null;
+    /** Manual refresh function */
+    refresh: () => Promise<void>;
+}
+/**
+ * Props for the React FeatureFlagProvider component.
+ */
+export interface FeatureFlagProviderProps<FeatureFlagKey extends string, FeatureFlags extends Record<FeatureFlagKey, FeatureFlagValue>> {
+    /** Provider configuration */
+    config: FeatureFlagConfig<FeatureFlagKey>;
+    /** Default context for flag evaluation */
+    defaultContext?: FeatureFlagContext;
+    /** Children components */
+    children: React.ReactNode;
+    /** Predefined feature flags and their values */
+    features: FeatureFlags;
+    /** Callback when provider is ready */
+    onReady?: (provider: FeatureFlagProvider<FeatureFlagKey>) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Whether to show loading state while initializing */
+    isShowLoading?: boolean;
+    /** Custom loading component */
+    loadingComponent?: React.ComponentType;
+    /** Custom error component */
+    errorComponent?: React.ComponentType<{
+        error: Error;
+        retry: () => void;
+    }>;
+}
+/**
+ * Backend Request DTO for flag creation.
+ */
+export interface CreateFlagRequest<FeatureFlagKey extends string> {
+    key: FeatureFlagKey;
+    name: string;
+    description?: string;
+    value: FeatureFlagValue;
+    isEnabled?: boolean;
+    environment?: 'all' | 'development' | 'staging' | 'production';
+    rolloutPercentage?: number;
+}
+/**
+ * Backend Provider health status information.
+ */
+export interface ProviderHealthStatus {
+    isInitialized: boolean;
+    provider: string;
+    isCacheEnabled: boolean;
+}
+/**
+ * Main interface for feature flag providers.
+ */
+export interface FeatureFlagProvider<FeatureFlagKey extends string> {
+    /** Initializes the provider by loading initial data */
+    initialize(): Promise<void>;
+    /** Evaluates a feature flag and returns full evaluation details */
+    getFlag(key: FeatureFlagKey, context?: FeatureFlagContext): Promise<FeatureFlagEvaluation<FeatureFlagKey>>;
+    /** Evaluates all feature flags for the given context */
+    getAllFlags(context?: FeatureFlagContext): Promise<Record<string, FeatureFlagEvaluation<FeatureFlagKey>>>;
+    /** Checks if a feature flag is enabled */
+    isEnabled(key: FeatureFlagKey, context?: FeatureFlagContext): Promise<boolean>;
+    /** Gets the value of a feature flag with optional type casting */
+    getValue<T = FeatureFlagValue>(key: FeatureFlagKey, context?: FeatureFlagContext): Promise<T>;
+    /** Refreshes the flag data from the underlying storage */
+    refresh(): Promise<void>;
+    /** Subscribes to flag changes and updates */
+    subscribe(callback: () => void): () => void;
+    /** Sets an override for a specific flag key */
+    setOverride(key: FeatureFlagKey, value: FeatureFlagValue): void;
+    /** Removes an override for a specific flag key */
+    removeOverride(key: FeatureFlagKey): void;
+    /** Clears all overrides */
+    clearOverrides(): void;
+    /** Disposes of the provider, cleaning up resources */
+    dispose(): void;
+}
+/**
+ * Partial mapping for flag overrides.
+ */
+export type FeatureFlagOverrides<FeatureFlagKey extends string = string> = Partial<{
+    [K in FeatureFlagKey]: FeatureFlagValue;
+}>;
+/**
+ * Hook-like interface for reactive feature flag usage.
+ */
+export type FeatureFlagHook<T = boolean> = {
+    /** The current value of the flag */
+    value: T;
+    /** Whether the flag is currently being loaded */
+    isLoading: boolean;
+    /** Any error that occurred during flag evaluation */
+    error: Error | null;
+    /** Function to manually refresh the flag value */
+    refresh: () => Promise<void>;
+};
+/**
+ * Helper functions for managing feature flags.
+ */
+export interface FeatureFlagHelpers<FeatureFlagKey extends string = string> {
+    setOverride: (key: FeatureFlagKey, value: FeatureFlagValue) => void;
+    removeOverride: (key: FeatureFlagKey) => void;
+    clearOverrides: () => void;
+    refresh: () => Promise<void>;
+    getMultipleFlags: (keys: FeatureFlagKey[], context?: FeatureFlagContext) => Promise<Record<FeatureFlagKey, FeatureFlagValue>>;
+    isAnyEnabled: (keys: FeatureFlagKey[], context?: FeatureFlagContext) => Promise<boolean>;
+    isAllEnabled: (keys: FeatureFlagKey[], context?: FeatureFlagContext) => Promise<boolean>;
+    whenEnabled: <T>(key: FeatureFlagKey, callback: () => T | Promise<T>, fallback?: () => T | Promise<T>, context?: FeatureFlagContext) => Promise<T | undefined>;
+}
+export interface FetchFeatureFlagDataResponse<FeatureFlagKey extends string> {
+    flags: FeatureFlag<FeatureFlagKey>[];
+    rules: FeatureFlagRule<FeatureFlagKey>[];
+}
+/**
+ * Input for error handling test cases
+ */
+export interface ErrorHandlingTestInput {
+    /** The error to test */
+    error: unknown;
+    /** Expected error message */
+    expectedMessage: string;
+    /** Expected HTTP status code */
+    expectedStatus: number;
+}
+/**
+ * Input for flag evaluation test cases
+ */
+export interface FlagEvaluationTestInput<FeatureFlagKey extends string> {
+    /** The flag key to evaluate */
+    flagKey: FeatureFlagKey;
+    /** Optional evaluation context */
+    context?: FeatureFlagContext;
+    /** Mock value to return */
+    mockValue: boolean;
+    /** Whether the flag is enabled */
+    isEnabled: boolean;
+}
+/**
+ * Input for flag creation test cases
+ */
+export interface FlagCreationTestInput<FeatureFlagKey extends string> {
+    /** Unique key for the flag */
+    key: FeatureFlagKey;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Flag value */
+    value: FeatureFlagValue;
+    /** Whether the flag is enabled */
+    isEnabled?: boolean;
+    /** Target environment */
+    environment?: 'all' | 'development' | 'production' | 'staging';
+    /** Rollout percentage (0-100) */
+    rolloutPercentage?: number;
+}
+/**
+ * Input for flag update test cases
+ */
+export interface FlagUpdateTestInput<FeatureFlagKey extends string> {
+    /** Key of the flag to update */
+    flagKey: FeatureFlagKey;
+    /** Update data object */
+    updateData: Record<string, unknown>;
+}
+/**
+ * Input for override test cases
+ */
+export interface OverrideTestInput<FeatureFlagKey extends string> {
+    /** Flag key to override */
+    flagKey: FeatureFlagKey;
+    /** Override value */
+    value: FeatureFlagValue;
+}
+/**
+ * Input for service initialization test cases
+ */
+export interface ServiceInitializationTestInput {
+    /** Environment variables to set */
+    envVars: Record<string, string>;
+    /** Expected configuration after initialization */
+    expectedConfig: {
+        /** Provider type */
+        provider: string;
+        /** Whether caching is enabled */
+        isCacheEnabled: boolean;
+        /** Cache TTL in seconds */
+        cacheTtl: number;
+        /** Refresh interval in seconds */
+        refreshInterval: number;
+        /** Whether to fallback to defaults on error */
+        shouldFallbackToDefaults: boolean;
+        /** Whether logging is enabled */
+        isLoggingEnabled: boolean;
+    };
+}
+/**
+ * Input for flag operation error test cases
+ */
+export interface FlagOperationErrorTestInput<FeatureFlagKey extends string> {
+    /** Flag key involved in the operation */
+    flagKey: FeatureFlagKey;
+    /** Error that occurred */
+    error: Error;
+    /** Expected log message */
+    expectedLogMessage: string;
+}
+/**
+ * Input for type inference test cases
+ */
+export interface TypeInferenceTestInput {
+    /** Value to infer type from */
+    value: unknown;
+    /** Expected type string */
+    expectedType: string;
+}
+/**
+ * Input for environment filter test cases
+ */
+export interface EnvironmentFilterTestInput {
+    /** Environment to filter by */
+    environment: string;
+    /** List of allowed environments */
+    allowedEnvironments: string[];
+}
+/**
+ * Input for timestamp behavior test cases
+ */
+export interface TimestampTestInput {
+    /** Operation type */
+    operation: 'create' | 'update';
+    /** Description of expected timestamp behavior */
+    expectedTimestampBehavior: string;
+}
+export interface ModuleConfigurationTestInput {
+    config: Record<string, unknown>;
+    expectedConfig: Record<string, unknown>;
+}
+export interface ProviderTypeTestInput {
+    provider: string;
+}
+export interface FlagOperationTestInput<FeatureFlagKey extends string> {
+    operation: 'create' | 'update' | 'delete' | 'evaluate';
+    flagKey: FeatureFlagKey;
+    data?: unknown;
+    context?: FeatureFlagContext;
+    expectedResult?: unknown;
+}
+export interface PermissionTestInput {
+    role: string;
+    operation: string;
+    resource: string;
+    expected: boolean;
+}
+export interface CacheOperationTestInput<FeatureFlagKey extends string> {
+    operation: 'set' | 'get' | 'refresh' | 'clear';
+    flagKey?: FeatureFlagKey;
+    expectedBehavior: string;
+}
+export interface RuleEvaluationTestInput<FeatureFlagKey extends string> {
+    flagKey: FeatureFlagKey;
+    rules: Array<{
+        conditions: Record<string, unknown>;
+        value: FeatureFlagValue;
+    }>;
+    context: FeatureFlagContext;
+    expectedValue: FeatureFlagValue;
+}
+export interface BatchOperationTestInput<FeatureFlagKey extends string> {
+    operations: Array<{
+        type: 'create' | 'update' | 'delete';
+        flagKey: FeatureFlagKey;
+        data?: unknown;
+    }>;
+    expectedResults: unknown[];
+}
+export interface ValidationTestInput {
+    input: unknown;
+    field: string;
+    expectedError?: string;
+    isValid: boolean;
+}
+export interface DynamicModuleTestInput {
+    config: Record<string, unknown>;
+    expectedProviders?: string[];
+    expectedImports?: string[];
+    expectedExports?: string[];
+}
+export interface AsyncModuleConfigTestInput {
+    imports?: string[];
+    inject?: string[];
+    useFactory?: (...args: unknown[]) => Record<string, unknown>;
+    expectedImports?: string[];
+    expectedProviders?: string[];
+}
+export interface RepositoryOperationTestInput {
+    operation: 'create' | 'update' | 'delete' | 'find';
+    data?: unknown;
+    expectedResult?: unknown;
+    shouldThrow?: boolean;
+}

package/dist/features/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './cache';
+export type * from './feature-flag';

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type * from './api';
+export * from './auth';
+export type * from './common';
+export type * from './entities';
+export * from './errors';
+export * from './events';
+export type * from './store';
+export type * from './ui';
+export * from './web3';
+export type * from './translations';
+export type * from './features';
+export type * from './testing';

package/dist/store/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/testing/common/assertions/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';

package/dist/testing/common/assertions/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Assertion Types
+ *
+ * Type definitions for assertion utilities.
+ */
+export interface ErrorPattern {
+    status: number;
+    message: RegExp;
+}
+export interface ValidationErrorPattern {
+    status: number;
+    validation: string[];
+}
+export interface ErrorMessagePattern {
+    message: RegExp;
+}
+export interface ErrorStats {
+    failures: number;
+    successes: number;
+    lastFailure?: Error;
+}
+export interface ErrorTimelineEntry {
+    timestamp: number;
+    error: Error;
+    context?: Record<string, unknown>;
+}
+export interface ExpectedError {
+    message?: string | RegExp;
+    type?: new (...args: unknown[]) => unknown;
+}
+export interface ValidationResponse {
+    message?: unknown[];
+}
+export interface HookResultValue<T> {
+    current: {
+        value: T;
+    };
+}
+export interface HookResultLoading {
+    current: {
+        isLoading: boolean;
+    };
+}
+export interface HookResultError {
+    current: {
+        error: Error | null;
+    };
+}
+export interface ErrorRecoveryResult {
+    error: Error;
+    recoveryResult: unknown;
+}
+export interface ErrorCorrelationEntry {
+    error: Error;
+    metadata?: Record<string, unknown>;
+}
+export interface ErrorTestScenario {
+    name: string;
+    fn: () => unknown | Promise<unknown>;
+    expectedError: unknown;
+    skip?: boolean;
+}
+export interface CircuitBreakerOptions {
+    failureThreshold: number;
+    resetTimeout: number;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onHalfOpen?: () => void;
+}
+export interface ErrorPropagationTestResult<T> {
+    propagatedTo: number;
+    finalError: Error;
+    intermediateResults: Array<T | Error>;
+}
+export interface ErrorCircuitBreaker<T> {
+    execute: (fn: () => T | Promise<T>) => Promise<T>;
+    getState: () => 'closed' | 'open' | 'half-open';
+    getStats: () => ErrorStats;
+    reset: () => void;
+}
+export interface ErrorCorrelator {
+    correlate: (error: Error, metadata?: Record<string, unknown>) => string;
+    getRelated: (correlationId: string) => Array<ErrorCorrelationEntry>;
+    getChain: (error: Error) => Array<ErrorCorrelationEntry>;
+}
+export interface ErrorMetrics {
+    record: (error: Error, context?: Record<string, unknown>) => void;
+    getMetrics: () => {
+        total: number;
+        byType: Record<string, number>;
+        byMessage: Record<string, number>;
+        timeline: Array<ErrorTimelineEntry>;
+        errorRate: (windowMs: number) => number;
+    };
+    reset: () => void;
+}
+export interface ErrorDeduplicator {
+    isDuplicate: (error: Error) => boolean;
+    record: (error: Error) => void;
+    getUniqueErrors: () => Error[];
+    reset: () => void;
+}
+export interface ErrorWithMessage {
+    message: string;
+}
+export interface ErrorWithResponse {
+    getResponse?: () => unknown;
+    response?: unknown;
+}
+export interface ValidationMessage {
+    property?: string;
+    constraints?: Record<string, string>;
+}
+export interface ExpectedHttpException {
+    status?: number;
+    message?: string | RegExp;
+    response?: unknown;
+}
+export interface ExpectedServiceError {
+    message?: string | RegExp;
+    type?: new (...args: unknown[]) => unknown;
+}
+export interface ErrorPropagationInjection {
+    atStep: number;
+    error: Error;
+}
+export interface ErrorEnrichmentContext {
+    operation?: string;
+    user?: string;
+    timestamp?: number;
+    requestId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ErrorDeduplicatorOptions {
+    keyFn?: (error: Error) => string;
+    windowMs?: number;
+}

package/dist/testing/common/factories/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';