@abdokouta/react-config 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,474 @@
+import { DynamicModule } from '@abdokouta/react-di';
+
+/**
+ * Configuration Module Options
+ */
+interface ConfigModuleOptions {
+    /**
+     * Configuration driver to use
+     * @default 'env'
+     */
+    driver?: 'env' | 'file' | 'firebase' | string;
+    /**
+     * Path to .env file (for env driver)
+     * @default '.env'
+     */
+    envFilePath?: string | string[];
+    /**
+     * Path pattern to scan for config files (for file driver)
+     * @example 'config/**\/*.config.ts'
+     */
+    filePattern?: string | string[];
+    /**
+     * Whether to ignore .env file
+     * @default false
+     */
+    ignoreEnvFile?: boolean;
+    /**
+     * Whether to expand environment variables
+     * @default false
+     */
+    expandVariables?: boolean;
+    /**
+     * Custom configuration object to merge
+     */
+    load?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
+    /**
+     * Whether configuration is global
+     * @default false
+     */
+    isGlobal?: boolean;
+    /**
+     * Cache configuration values
+     * @default true
+     */
+    cache?: boolean;
+    /**
+     * Validate configuration on load
+     */
+    validate?: (config: Record<string, any>) => void | Promise<void>;
+    /**
+     * Firebase configuration (for firebase driver)
+     */
+    firebase?: {
+        projectId: string;
+        configPath?: string;
+    };
+    /**
+     * Environment variable prefix to strip
+     * Set to 'auto' to auto-detect (VITE_ for Vite, NEXT_PUBLIC_ for Next.js)
+     * Set to 'VITE_' or 'NEXT_PUBLIC_' for specific framework
+     * Set to a custom string to strip that prefix
+     * Set to false to disable prefix stripping
+     * @default 'auto'
+     * @example 'VITE_' - strips VITE_ prefix, so VITE_APP_NAME becomes APP_NAME
+     * @example 'NEXT_PUBLIC_' - strips NEXT_PUBLIC_ prefix, so NEXT_PUBLIC_API_URL becomes API_URL
+     * @example 'auto' - auto-detects framework and strips appropriate prefix
+     */
+    envPrefix?: 'auto' | 'VITE_' | 'NEXT_PUBLIC_' | string | false;
+    /**
+     * Global variable name to read config from in browser
+     * @default '__APP_CONFIG__'
+     * @example '__APP_CONFIG__' - reads from window.__APP_CONFIG__
+     */
+    globalName?: string;
+}
+
+/**
+ * Configuration Module
+ *
+ * Provides configuration management with multiple drivers.
+ * Similar to NestJS ConfigModule.
+ *
+ * @example
+ * ```typescript
+ * // Using environment variables (default)
+ * @Module({
+ *   imports: [
+ *     ConfigModule.forRoot({
+ *       envFilePath: '.env',
+ *       isGlobal: true,
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using file-based configuration
+ * @Module({
+ *   imports: [
+ *     ConfigModule.forRoot({
+ *       driver: 'file',
+ *       filePattern: 'config/**\/*.config.ts',
+ *       isGlobal: true,
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+declare class ConfigModule {
+    /**
+     * Register configuration module with options
+     *
+     * @param options - Configuration options
+     * @returns Dynamic module
+     */
+    static forRoot(options?: ConfigModuleOptions): DynamicModule;
+    /**
+     * Register configuration module asynchronously
+     *
+     * @param options - Async configuration options
+     * @returns Dynamic module
+     */
+    static forRootAsync(options: ConfigModuleOptions & {
+        useFactory?: () => Promise<ConfigModuleOptions> | ConfigModuleOptions;
+    }): Promise<DynamicModule>;
+    /**
+     * Create configuration driver based on options
+     */
+    private static createDriver;
+    /**
+     * Merge custom configuration into driver
+     */
+    private static mergeCustomConfig;
+}
+
+/**
+ * Configuration Driver Interface
+ *
+ * Defines the contract for configuration drivers (env, file, firebase, etc.)
+ */
+interface ConfigDriver {
+    /**
+     * Load configuration from the driver source
+     * @returns Configuration object
+     */
+    load(): Promise<Record<string, any>> | Record<string, any>;
+    /**
+     * Get a configuration value by key
+     * @param key - Configuration key (supports dot notation)
+     * @param defaultValue - Default value if key not found
+     */
+    get<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if a configuration key exists
+     * @param key - Configuration key
+     */
+    has(key: string): boolean;
+    /**
+     * Get all configuration values
+     */
+    all(): Record<string, any>;
+}
+
+/**
+ * Configuration Service Interface
+ *
+ * Defines the contract for configuration service implementations.
+ */
+interface ConfigServiceInterface {
+    /**
+     * Get configuration value
+     */
+    get<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Get configuration value or throw if not found
+     */
+    getOrThrow<T = any>(key: string): T;
+    /**
+     * Get string value
+     */
+    getString(key: string, defaultValue?: string): string | undefined;
+    /**
+     * Get string value or throw
+     */
+    getStringOrThrow(key: string): string;
+    /**
+     * Get number value
+     */
+    getNumber(key: string, defaultValue?: number): number | undefined;
+    /**
+     * Get number value or throw
+     */
+    getNumberOrThrow(key: string): number;
+    /**
+     * Get boolean value
+     */
+    getBool(key: string, defaultValue?: boolean): boolean | undefined;
+    /**
+     * Get boolean value or throw
+     */
+    getBoolOrThrow(key: string): boolean;
+    /**
+     * Get array value
+     */
+    getArray(key: string, defaultValue?: string[]): string[] | undefined;
+    /**
+     * Get JSON value
+     */
+    getJson<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if configuration key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get all configuration values
+     */
+    all(): Record<string, any>;
+    /**
+     * Clear cache
+     */
+    clearCache(): void;
+}
+
+/**
+ * Configuration Service
+ *
+ * Provides type-safe access to configuration values with various getter methods.
+ * Similar to NestJS ConfigService.
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   constructor(private config: ConfigService) {}
+ *
+ *   getDbConfig() {
+ *     return {
+ *       host: this.config.getString('DB_HOST', 'localhost'),
+ *       port: this.config.getNumber('DB_PORT', 5432),
+ *       ssl: this.config.getBool('DB_SSL', false),
+ *     };
+ *   }
+ * }
+ * ```
+ */
+declare class ConfigService implements ConfigServiceInterface {
+    private driver;
+    constructor(driver: ConfigDriver);
+    /**
+     * Get configuration value
+     */
+    get<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Get configuration value or throw if not found
+     */
+    getOrThrow<T = any>(key: string): T;
+    /**
+     * Get string value
+     */
+    getString(key: string, defaultValue?: string): string | undefined;
+    /**
+     * Get string value or throw
+     */
+    getStringOrThrow(key: string): string;
+    /**
+     * Get number value
+     */
+    getNumber(key: string, defaultValue?: number): number | undefined;
+    /**
+     * Get number value or throw
+     */
+    getNumberOrThrow(key: string): number;
+    /**
+     * Get boolean value
+     * Treats 'true', '1', 'yes', 'on' as true
+     */
+    getBool(key: string, defaultValue?: boolean): boolean | undefined;
+    /**
+     * Get boolean value or throw
+     */
+    getBoolOrThrow(key: string): boolean;
+    /**
+     * Get array value (comma-separated string or actual array)
+     */
+    getArray(key: string, defaultValue?: string[]): string[] | undefined;
+    /**
+     * Get JSON value
+     */
+    getJson<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if configuration key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get all configuration values
+     */
+    all(): Record<string, any>;
+    /**
+     * Clear cache (no-op since we don't cache in ConfigService)
+     */
+    clearCache(): void;
+}
+
+/**
+ * Environment Variable Configuration Driver
+ *
+ * Loads configuration from environment variables (process.env).
+ * Supports .env files via dotenv.
+ */
+declare class EnvDriver implements ConfigDriver {
+    private options;
+    private config;
+    private loaded;
+    constructor(options?: {
+        envFilePath?: string | string[];
+        ignoreEnvFile?: boolean;
+        expandVariables?: boolean;
+        envPrefix?: string | false;
+        globalName?: string;
+    });
+    /**
+     * Load environment variables
+     */
+    load(): Record<string, any>;
+    /**
+     * Get configuration value
+     */
+    get<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get all configuration
+     */
+    all(): Record<string, any>;
+    /**
+     * Load .env file using dotenv
+     */
+    private loadDotEnv;
+    /**
+     * Expand environment variables (e.g., ${VAR_NAME})
+     */
+    private expandEnvVariables;
+    /**
+     * Strip environment variable prefix
+     * Auto-detects framework (Vite, Next.js) or uses custom prefix
+     */
+    private stripPrefix;
+}
+
+/**
+ * File-based Configuration Driver
+ *
+ * Loads configuration from TypeScript/JavaScript files.
+ * This is a server-side only driver. For client-side, use the Vite plugin.
+ *
+ * @see packages/pixielity/config/src/plugins/vite-config.plugin.ts
+ */
+declare class FileDriver implements ConfigDriver {
+    private config;
+    private loaded;
+    constructor(options?: {
+        config?: Record<string, any>;
+    });
+    /**
+     * Load configuration
+     * Config should be pre-loaded via Vite plugin or passed in constructor
+     */
+    load(): Promise<Record<string, any>>;
+    /**
+     * Get configuration value
+     */
+    get<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get all configuration
+     */
+    all(): Record<string, any>;
+}
+
+/**
+ * Vite Config Plugin Options Interface
+ *
+ * Configuration options for the Vite config plugin that injects
+ * environment variables into the browser.
+ */
+interface ViteConfigPluginOptions {
+    /**
+     * Environment variables loaded by Vite's loadEnv
+     * Pass the result of loadEnv(mode, envDir, '') here
+     */
+    env?: Record<string, string>;
+    /**
+     * Scan and collect .config.ts files
+     * @default false (disabled by default to avoid Node.js module issues)
+     */
+    scanConfigFiles?: boolean;
+    /**
+     * Pattern to match config files
+     * @default 'src/**\/*.config.ts'
+     */
+    configFilePattern?: string | string[];
+    /**
+     * Directories to exclude from config file scanning
+     * @default ['node_modules', 'dist', 'build', '.git']
+     */
+    excludeDirs?: string[];
+    /**
+     * Root directory for scanning config files
+     * @default process.cwd()
+     */
+    root?: string;
+    /**
+     * Include all environment variables
+     * @default true
+     */
+    includeAll?: boolean;
+    /**
+     * Specific environment variables to include
+     * Only used if includeAll is false
+     */
+    include?: string[];
+    /**
+     * Global variable name to inject config into
+     * @default '__APP_CONFIG__'
+     */
+    globalName?: string;
+}
+
+/**
+ * Get nested value from object using dot notation
+ *
+ * @param obj - Source object
+ * @param path - Dot-notated path (e.g., 'database.host')
+ * @param defaultValue - Default value if path not found
+ * @returns Value at path or default value
+ *
+ * @example
+ * ```typescript
+ * const config = { database: { host: 'localhost' } };
+ * getNestedValue(config, 'database.host'); // 'localhost'
+ * getNestedValue(config, 'database.port', 5432); // 5432
+ * ```
+ */
+declare function getNestedValue<T = any>(obj: Record<string, any>, path: string, defaultValue?: T): T | undefined;
+/**
+ * Check if nested path exists in object
+ *
+ * @param obj - Source object
+ * @param path - Dot-notated path
+ * @returns True if path exists
+ */
+declare function hasNestedValue(obj: Record<string, any>, path: string): boolean;
+
+/**
+ * Load Config File Utility
+ *
+ * Dynamically loads and parses a config file.
+ */
+/**
+ * Load and parse config file
+ *
+ * @param filePath - Absolute path to the config file
+ * @returns Parsed config object
+ */
+declare function loadConfigFile(filePath: string): Promise<Record<string, any>>;
+
+export { type ConfigDriver, ConfigModule, type ConfigModuleOptions, ConfigService, type ConfigServiceInterface, EnvDriver, FileDriver, type ViteConfigPluginOptions, getNestedValue, hasNestedValue, loadConfigFile };