@plyaz/types 1.18.1 → 1.18.3

package/dist/core/events/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Core Events Types
+ */
+export type { CoreCrudOperation, CoreValidationStartedPayload, CoreValidationSuccessPayload, CoreValidationFailedPayload, CoreSanitizationStartedPayload, CoreSanitizationSuccessPayload, CoreSanitizationFailedPayload, CoreEntityCreatedPayload, CoreEntityUpdatedPayload, CoreEntityPatchedPayload, CoreEntityDeletedPayload, CoreEntityCreatingPayload, CoreEntityUpdatingPayload, CoreEntityPatchingPayload, CoreEntityDeletingPayload, CoreEntityErrorPayload, CoreEntityCompletePayload, CoreBulkCreatedPayload, CoreBulkDeletedPayload, } from './payloads';

package/dist/core/events/payloads.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Core Event Payloads for CoreEventManager
+ *
+ * Base payload types that domains can extend for type-safe events.
+ * All types prefixed with `Core` to avoid conflicts with domain-specific types.
+ *
+ * @example
+ * ```typescript
+ * // Extending for a specific domain
+ * interface CampaignCreatedPayload extends CoreEntityCreatedPayload<Campaign, CampaignStoreItem> {
+ *   notifyFollowers?: boolean;
+ * }
+ * ```
+ */
+/**
+ * CRUD operation types
+ */
+export type CoreCrudOperation = 'create' | 'update' | 'patch' | 'delete' | 'query';
+/**
+ * Payload for validation:started events
+ */
+export interface CoreValidationStartedPayload {
+    operation: CoreCrudOperation;
+    entityId?: string;
+    data: unknown;
+}
+/**
+ * Payload for validation:success events
+ */
+export interface CoreValidationSuccessPayload<TValidated = unknown> {
+    operation: CoreCrudOperation;
+    entityId?: string;
+    validatedData: TValidated;
+}
+/**
+ * Payload for validation:failed events
+ */
+export interface CoreValidationFailedPayload {
+    operation: CoreCrudOperation;
+    entityId?: string;
+    error: unknown;
+}
+/**
+ * Payload for sanitization:started events
+ */
+export interface CoreSanitizationStartedPayload {
+    operation: CoreCrudOperation;
+    entityId?: string;
+    data: unknown;
+}
+/**
+ * Payload for sanitization:success events
+ */
+export interface CoreSanitizationSuccessPayload<TSanitized = unknown> {
+    operation: CoreCrudOperation;
+    entityId?: string;
+    sanitizedData: TSanitized;
+    changedFields?: string[];
+}
+/**
+ * Payload for sanitization:failed events
+ */
+export interface CoreSanitizationFailedPayload {
+    operation: CoreCrudOperation;
+    entityId?: string;
+    error: unknown;
+}
+/**
+ * Payload for entity:created events
+ *
+ * @typeParam TEntity - Domain entity type
+ * @typeParam TStoreState - Serializable store state type
+ */
+export interface CoreEntityCreatedPayload<TEntity, TStoreState = TEntity> {
+    entity: TEntity;
+    storeState: TStoreState;
+}
+/**
+ * Payload for entity:updated events
+ *
+ * @typeParam TEntity - Domain entity type
+ * @typeParam TStoreState - Serializable store state type
+ */
+export interface CoreEntityUpdatedPayload<TEntity, TStoreState = TEntity> {
+    entity: TEntity;
+    storeState: TStoreState;
+    previousState?: TStoreState;
+}
+/**
+ * Payload for entity:patched events (partial update)
+ *
+ * @typeParam TEntity - Domain entity type
+ * @typeParam TStoreState - Serializable store state type
+ */
+export interface CoreEntityPatchedPayload<TEntity, TStoreState = TEntity> {
+    entity: TEntity;
+    storeState: TStoreState;
+    changedFields?: (keyof TEntity)[];
+}
+/**
+ * Payload for entity:deleted events
+ */
+export interface CoreEntityDeletedPayload {
+    id: string;
+    soft: boolean;
+}
+/**
+ * Payload for entity:creating events (before API call)
+ */
+export interface CoreEntityCreatingPayload<TRequest> {
+    request: TRequest;
+}
+/**
+ * Payload for entity:updating events (before API call)
+ */
+export interface CoreEntityUpdatingPayload<TRequest> {
+    id: string;
+    request: TRequest;
+}
+/**
+ * Payload for entity:patching events (before API call)
+ */
+export interface CoreEntityPatchingPayload<TRequest> {
+    id: string;
+    request: TRequest;
+}
+/**
+ * Payload for entity:deleting events (before API call)
+ */
+export interface CoreEntityDeletingPayload {
+    id: string;
+    options?: {
+        soft: boolean;
+    };
+}
+/**
+ * Payload for entity:*:error events
+ */
+export interface CoreEntityErrorPayload {
+    error: unknown;
+    entityId?: string;
+}
+/**
+ * Payload for entity:*:complete events (regardless of success/failure)
+ */
+export interface CoreEntityCompletePayload {
+    success?: boolean;
+    entityId?: string;
+}
+/**
+ * Payload for bulk entity creation
+ *
+ * @typeParam TEntity - Domain entity type
+ * @typeParam TStoreState - Serializable store state type
+ */
+export interface CoreBulkCreatedPayload<TEntity, TStoreState = TEntity> {
+    entities: TEntity[];
+    storeStates: TStoreState[];
+    total: number;
+}
+/**
+ * Payload for bulk entity deletion
+ */
+export interface CoreBulkDeletedPayload {
+    ids: string[];
+    soft: boolean;
+    total: number;
+}

package/dist/core/featureFlag/enums.d.ts

@@ -6,9 +6,9 @@ export declare enum SORT_DIRECTION {
     Desc = "desc"
 }
 /**
- * Database table names enumeration
+ * Feature flag database table names enumeration
  */
-export declare enum DATABASE_TABLE {
+export declare enum FEATURE_FLAG_TABLE {
     FeatureFlags = "feature_flags",
     FeatureFlagRules = "feature_flag_rules",
     FeatureFlagEvaluations = "feature_flag_evaluations",
@@ -19,7 +19,9 @@ export declare enum DATABASE_TABLE {
  */
 export declare enum FEATURE_FLAG_FIELD {
     Key = "key",
+    Name = "name",
     Value = "value",
+    Type = "type",
     IsEnabled = "is_enabled",
     Environments = "environments",
     Description = "description",
@@ -78,12 +80,15 @@ export declare enum SYSTEM_USERS {
 }
 /**
  * Evaluation Reasons
+ * Must match database enum: evaluation_reason
+ * Used when logging feature flag evaluations to audit table
  */
 export declare enum EVALUATION_REASONS {
-    EVALUATION = "evaluation",
-    DefaultValue = "default_value",
-    RuleMatch = "rule_match",
-    OVERRIDE = "override"
+    Default = "default",// Default flag value used
+    RuleMatch = "rule_match",// Matched a targeting rule
+    Rollout = "rollout",// Matched rollout percentage
+    Override = "override",// User-specific override applied
+    Disabled = "disabled"
 }
 /**
  * Feature Flag Types

package/dist/core/featureFlag/types.d.ts

@@ -7,6 +7,7 @@
  */
 import type { FEATURES } from '@plyaz/config';
 import type { FeatureFlagCondition, FeatureFlagConfig, FeatureFlagValue } from '../../features';
+import type { ApiClientWithEvents } from '../../api';
 /**
  * Raw database row interface for feature flags table
  */
@@ -55,8 +56,10 @@ export interface DatabaseEvaluationRow {
     flag_key: string;
     user_id?: string;
     context?: Record<string, string | number | boolean>;
-    result: FeatureFlagValue;
+    value: FeatureFlagValue;
+    is_enabled: boolean;
     reason: string;
+    matched_rule_id?: string;
     evaluated_at: string;
 }
 /**
@@ -110,3 +113,145 @@ export interface FeatureFlagEnvironmentConfig extends Omit<FeatureFlagConfig<Fea
  */
 export type FeatureFlagKey = keyof typeof FEATURES;
 export type FeatureFlags = typeof FEATURES extends Record<FeatureFlagKey, FeatureFlagValue> ? typeof FEATURES : never;
+/**
+ * Feature flag module configuration for NestJS/Core integration
+ */
+export interface CoreFeatureFlagModuleConfig {
+    /** Provider type for flag storage */
+    provider?: 'memory' | 'database' | 'redis' | 'api' | 'file';
+    /** How often to refresh flag data in seconds (0 = no auto-refresh) */
+    refreshInterval?: number;
+    /** Enable debug logging */
+    loggingEnabled?: boolean;
+    /** Database configuration (optional - uses defaults if provider is 'database') */
+    db?: {
+        /** Table name for feature flags (default: 'feature_flags') */
+        tableName?: string;
+        /** Table name for feature flag rules (default: 'feature_flag_rules') */
+        rulesTableName?: string;
+        /** Table name for feature flag evaluations (default: 'feature_flag_evaluations') */
+        evaluationsTableName?: string;
+        /** Table name for feature flag overrides (default: 'feature_flag_overrides') */
+        overridesTableName?: string;
+        /** Schema for evaluations table (default: 'public', use 'audit' for partitioned tables) */
+        evaluationsSchema?: string;
+    };
+    /** Redis configuration (required if provider is 'redis') */
+    redis?: {
+        /** Redis connection URL (e.g., 'redis://localhost:6379') */
+        url: string;
+        /** Key prefix for feature flags (default: 'feature_flags:') */
+        keyPrefix?: string;
+    };
+    /**
+     * API configuration (for provider: 'api')
+     * Uses @plyaz/api package with predefined endpoints (e.g., api.fetchFeatureFlags())
+     * Similar to BaseAdapter apiClientConfig pattern
+     *
+     * @example
+     * ```typescript
+     * // Option 1: Provide config (ApiClientService created internally)
+     * FeatureFlagModule.forRoot({
+     *   provider: 'api',
+     *   api: {
+     *     clientConfig: {
+     *       baseURL: 'https://flags.example.com',
+     *       timeout: 5000,
+     *       headers: { static: { 'X-API-Key': '...' } }
+     *     }
+     *   }
+     * })
+     *
+     * // Option 2: Inject existing ApiClientService (for shared client)
+     * FeatureFlagModule.forRoot({
+     *   provider: 'api',
+     *   api: { client: existingApiClientService }
+     * })
+     * ```
+     */
+    api?: {
+        /**
+         * API client configuration (follows ApiConfig from @plyaz/types/api)
+         * Used to create a dedicated ApiClientService for feature flags
+         */
+        clientConfig?: {
+            /** Base URL for the feature flags API service */
+            baseURL: string;
+            /** Request timeout in milliseconds */
+            timeout?: number;
+            /** Headers configuration */
+            headers?: {
+                /** Static headers included in all requests */
+                static?: Record<string, string>;
+                /** Dynamic headers generated per request */
+                dynamic?: Record<string, () => string | Promise<string>>;
+            };
+            /** Retry configuration */
+            retry?: {
+                maxRetries?: number;
+                retryDelay?: number;
+            };
+        };
+        /**
+         * Inject an existing ApiClientService instance
+         * Useful when sharing a client across services or for testing
+         *
+         * @example
+         * ```typescript
+         * import { ApiClientService } from '@plyaz/core';
+         *
+         * // Initialize the service first
+         * await ApiClientService.init({ env: 'production' }, { baseURL: '...' });
+         *
+         * // Then inject it
+         * FeatureFlagModule.forRoot({
+         *   provider: 'api',
+         *   api: { client: ApiClientService.getClient() }
+         * })
+         * ```
+         */
+        client?: ApiClientWithEvents<unknown, unknown>;
+    };
+    /** File configuration (optional - uses defaults if provider is 'file') */
+    file?: {
+        /** Path to the feature flags file (default: './feature-flags.json') */
+        path?: string;
+        /** File format: 'json' or 'yaml' (default: 'json') */
+        format?: 'json' | 'yaml';
+        /** Watch file for changes (default: false) */
+        watch?: boolean;
+    };
+    /** Cache configuration */
+    cache?: {
+        /** Enable caching of flag evaluations (default: true) */
+        enabled?: boolean;
+        /** Cache time-to-live in seconds (default: 300) */
+        ttl?: number;
+    };
+}
+/**
+ * Configuration for database table names.
+ * Allows customization of table names for different environments (dev, test, prod).
+ */
+export interface FeatureFlagTableConfig {
+    /** Table name for feature flags (default: 'feature_flags') */
+    flagsTable: string;
+    /** Table name for feature flag rules (default: 'feature_flag_rules') */
+    rulesTable: string;
+    /** Table name for feature flag evaluations (default: 'feature_flag_evaluations') */
+    evaluationsTable: string;
+    /** Table name for feature flag overrides (default: 'feature_flag_overrides') */
+    overridesTable: string;
+    /** Schema for evaluations table (default: 'public') */
+    evaluationsSchema: string;
+}
+/**
+ * Feature flag request type for middleware
+ * Extended request object with feature flag properties
+ */
+export interface CoreFeatureFlagRequest {
+    featureFlags?: Record<string, boolean>;
+    query?: Record<string, unknown> | URLSearchParams;
+    headers?: Record<string, string | string[] | undefined>;
+    url?: string;
+}

package/dist/core/index.d.ts

@@ -6,9 +6,12 @@
  */
 export type { ApiEnvironmentConfig, ApiProviderProps } from './services';
 export type { CoreIdempotencyStoreType, CoreInMemoryIdempotencyAdapterConfig, CoreRedisIdempotencyAdapterConfig, CoreIdempotencyStoreOptions, CoreIdempotencyStoreConfig, } from './idempotency';
+export type { CoreServices, CoreRouteContext, CoreRouteHandler, CoreRouteDefinition, CoreModuleConfigSchema, CoreServiceFactory, CoreModuleLifecycle, CoreModuleDefinition, CoreRegisteredModule, CoreConfiguredModule, CoreModuleFactory, CoreFrameworkType, CoreServerConfig, CoreFrameworkAdapter, CoreAdapterFactory, CoreRuntimeEnvironment, CoreRuntimeContext, CoreNextJsHandlerContext, CoreNextJsHandlerResult, CoreNextJsHandler, CoreNextJsHandlerOptions, CoreEnvVars, CoreAppEnvironment, CoreApiInitOptions, CoreInitOptions, CoreServicesResult, CoreNestJsModuleOptions, CoreNestJsModuleAsyncOptions, } from './modules';
+export { BACKEND_RUNTIMES, FRONTEND_RUNTIMES, UNIVERSAL_RUNTIMES } from './modules';
 export * from './tables/enum';
 export type * from './auth/types';
 export type * from './featureFlag/types';
 export * from './featureFlag/enums';
 export * from './featureFlag/constants';
+export type * from './events';
 export type * from './types';