@abdokouta/react-config 1.0.0

package/src/interfaces/config-service.interface.ts

@@ -0,0 +1,71 @@
+/**
+ * Configuration Service Interface
+ * 
+ * Defines the contract for configuration service implementations.
+ */
+export 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;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Interfaces
+ */
+
+export type { ConfigDriver } from './config-driver.interface';
+export type { ConfigModuleOptions } from './config-module-options.interface';
+export type { ConfigServiceInterface } from './config-service.interface';
+export type { ViteConfigPluginOptions } from './vite-config-plugin-options.interface';

package/src/interfaces/vite-config-plugin-options.interface.ts

@@ -0,0 +1,56 @@
+/**
+ * Vite Config Plugin Options Interface
+ *
+ * Configuration options for the Vite config plugin that injects
+ * environment variables into the browser.
+ */
+
+export 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;
+}

package/src/plugins/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Plugins
+ */
+
+export { viteConfigPlugin } from './vite.plugin';

package/src/plugins/vite.plugin.ts

@@ -0,0 +1,115 @@
+/**
+ * Vite Plugin for Config Package
+ *
+ * Simple plugin that receives env from Vite's loadEnv and injects it into the browser.
+ * Does NOT apply any business logic - that's handled by ConfigService.
+ * 
+ * Responsibilities:
+ * 1. Receive environment variables from Vite's loadEnv (passed via options)
+ * 2. Inject them into window.__APP_CONFIG__ (or custom global name)
+ * 3. Optionally scan and collect .config.ts files
+ * 
+ * ConfigService will then query from window.__APP_CONFIG__ and apply:
+ * - Prefix stripping
+ * - Type conversion
+ * - Validation
+ * - Defaults
+ * 
+ * Usage:
+ * ```ts
+ * import { defineConfig, loadEnv } from 'vite'
+ * import { viteConfigPlugin } from '@abdokouta/config/vite-plugin'
+ * 
+ * export default defineConfig(({ mode }) => {
+ *   const env = loadEnv(mode, 'environments', '')
+ *   
+ *   return {
+ *     plugins: [
+ *       viteConfigPlugin({ env })
+ *     ]
+ *   }
+ * })
+ * ```
+ */
+
+import path from 'path';
+import type { Plugin } from 'vite';
+import type { ViteConfigPluginOptions } from '@/interfaces/vite-config-plugin-options.interface';
+import { scanConfigFiles } from '@/utils/scan-config-files.util';
+import { loadConfigFile } from '@/utils/load-config-file.util';
+
+/**
+ * Vite plugin that injects environment variables into the browser
+ * 
+ * This plugin is DUMB - it just receives env and injects it.
+ * ConfigService is SMART - it queries and applies business logic.
+ */
+export function viteConfigPlugin(options: ViteConfigPluginOptions = {}): Plugin {
+  const {
+    env = {},
+    includeAll = true,
+    include = [],
+    scanConfigFiles: shouldScanConfigFiles = false,
+    globalName = '__APP_CONFIG__',
+  } = options;
+
+  let collectedConfig: Record<string, any> = {};
+
+  return {
+    name: 'vite-plugin-config',
+
+    async configResolved(config) {
+      // Scan and collect config files (optional, disabled by default)
+      if (shouldScanConfigFiles) {
+        const configFiles = await scanConfigFiles({
+          ...options,
+          root: config.root,
+        });
+
+        console.log('[vite-plugin-config] Found config files:', configFiles.length);
+        
+        // Load all config files and merge them
+        for (const file of configFiles) {
+          const fileConfig = await loadConfigFile(file);
+          collectedConfig = { ...collectedConfig, ...fileConfig };
+          console.log('[vite-plugin-config] Loaded config from:', path.relative(config.root, file));
+        }
+      }
+    },
+
+    transformIndexHtml(html) {
+      // Build the config object from provided env
+      const processEnv: Record<string, any> = {};
+
+      for (const [key, value] of Object.entries(env)) {
+        // Filter by include list if not including all
+        if (!includeAll && !include.includes(key)) {
+          continue;
+        }
+
+        // Just copy the value as-is (NO prefix stripping here)
+        processEnv[key] = value;
+      }
+
+      // Merge with collected config from .config.ts files
+      const finalConfig = { ...processEnv, ...collectedConfig };
+
+      console.log('[vite-plugin-config] Injecting environment variables into HTML');
+      console.log('[vite-plugin-config] Total variables:', Object.keys(finalConfig).length);
+      console.log('[vite-plugin-config] Sample keys:', Object.keys(finalConfig).filter(k => k.includes('APP') || k.includes('VITE')));
+      console.log('[vite-plugin-config] Global name:', globalName);
+
+      // Inject script into HTML head
+      const script = `
+        <script>
+          window.${globalName} = ${JSON.stringify(finalConfig)};
+          // Also set process.env for backward compatibility
+          window.process = window.process || {};
+          window.process.env = window.${globalName};
+        </script>
+      `;
+
+      return html.replace('<head>', `<head>${script}`);
+    },
+  };
+}

package/src/services/config.service.ts

@@ -0,0 +1,172 @@
+import { Inject, Injectable } from "@abdokouta/react-di";
+
+import { CONFIG_DRIVER } from "@/constants/tokens.constant";
+import type { ConfigDriver } from "@/interfaces/config-driver.interface";
+import type { ConfigServiceInterface } from "@/interfaces/config-service.interface";
+
+/**
+ * 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),
+ *     };
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class ConfigService implements ConfigServiceInterface {
+  constructor(
+    @Inject(CONFIG_DRIVER)
+    private driver: ConfigDriver,
+  ) {}
+
+  /**
+   * Get configuration value
+   */
+  get<T = any>(key: string, defaultValue?: T): T | undefined {
+    return this.driver.get<T>(key, defaultValue);
+  }
+
+  /**
+   * Get configuration value or throw if not found
+   */
+  getOrThrow<T = any>(key: string): T {
+    const value = this.get<T>(key);
+    if (value === undefined) {
+      throw new Error(`Configuration key "${key}" is required but not set`);
+    }
+    return value;
+  }
+
+  /**
+   * Get string value
+   */
+  getString(key: string, defaultValue?: string): string | undefined {
+    const value = this.get(key, defaultValue);
+    return value !== undefined ? String(value) : undefined;
+  }
+
+  /**
+   * Get string value or throw
+   */
+  getStringOrThrow(key: string): string {
+    return String(this.getOrThrow(key));
+  }
+
+  /**
+   * Get number value
+   */
+  getNumber(key: string, defaultValue?: number): number | undefined {
+    const value = this.get(key, defaultValue);
+    if (value === undefined) {
+      return undefined;
+    }
+    const parsed = Number(value);
+    return isNaN(parsed) ? defaultValue : parsed;
+  }
+
+  /**
+   * Get number value or throw
+   */
+  getNumberOrThrow(key: string): number {
+    const value = this.getNumber(key);
+    if (value === undefined) {
+      throw new Error(`Configuration key "${key}" is required but not set`);
+    }
+    return value;
+  }
+
+  /**
+   * Get boolean value
+   * Treats 'true', '1', 'yes', 'on' as true
+   */
+  getBool(key: string, defaultValue?: boolean): boolean | undefined {
+    const value = this.get(key, defaultValue);
+    if (value === undefined) {
+      return undefined;
+    }
+    if (typeof value === "boolean") {
+      return value;
+    }
+    return ["true", "1", "yes", "on"].includes(String(value).toLowerCase());
+  }
+
+  /**
+   * Get boolean value or throw
+   */
+  getBoolOrThrow(key: string): boolean {
+    const value = this.getBool(key);
+    if (value === undefined) {
+      throw new Error(`Configuration key "${key}" is required but not set`);
+    }
+    return value;
+  }
+
+  /**
+   * Get array value (comma-separated string or actual array)
+   */
+  getArray(key: string, defaultValue?: string[]): string[] | undefined {
+    const value = this.get(key, defaultValue);
+    if (value === undefined) {
+      return undefined;
+    }
+    if (Array.isArray(value)) {
+      return value.map(String);
+    }
+    return String(value)
+      .split(",")
+      .map((v) => v.trim())
+      .filter(Boolean);
+  }
+
+  /**
+   * Get JSON value
+   */
+  getJson<T = any>(key: string, defaultValue?: T): T | undefined {
+    const value = this.get(key, defaultValue);
+    if (value === undefined) {
+      return undefined;
+    }
+    if (typeof value === "object") {
+      return value as T;
+    }
+    try {
+      return JSON.parse(String(value)) as T;
+    } catch {
+      return defaultValue;
+    }
+  }
+
+  /**
+   * Check if configuration key exists
+   */
+  has(key: string): boolean {
+    return this.driver.has(key);
+  }
+
+  /**
+   * Get all configuration values
+   */
+  all(): Record<string, any> {
+    return this.driver.all();
+  }
+
+  /**
+   * Clear cache (no-op since we don't cache in ConfigService)
+   */
+  clearCache(): void {
+    // No-op - caching should be done at a higher level if needed
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Services
+ */
+
+export { ConfigService } from './config.service';

package/src/utils/get-nested-value.util.ts

@@ -0,0 +1,56 @@
+/**
+ * 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
+ * ```
+ */
+export function getNestedValue<T = any>(
+  obj: Record<string, any>,
+  path: string,
+  defaultValue?: T
+): T | undefined {
+  const keys = path.split('.');
+  let current: any = obj;
+
+  for (const key of keys) {
+    if (current === null || current === undefined) {
+      return defaultValue;
+    }
+    current = current[key];
+  }
+
+  return current !== undefined ? current : defaultValue;
+}
+
+/**
+ * Check if nested path exists in object
+ * 
+ * @param obj - Source object
+ * @param path - Dot-notated path
+ * @returns True if path exists
+ */
+export function hasNestedValue(
+  obj: Record<string, any>,
+  path: string
+): boolean {
+  const keys = path.split('.');
+  let current: any = obj;
+
+  for (const key of keys) {
+    if (current === null || current === undefined || !(key in current)) {
+      return false;
+    }
+    current = current[key];
+  }
+
+  return true;
+}

package/src/utils/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Utils
+ */
+
+export { getNestedValue, hasNestedValue } from './get-nested-value.util';
+export { loadConfigFile } from './load-config-file.util';

package/src/utils/load-config-file.util.ts

@@ -0,0 +1,37 @@
+/**
+ * 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
+ */
+export async function loadConfigFile(
+  filePath: string
+): Promise<Record<string, any>> {
+  try {
+    // Dynamic import of the config file
+    // @ts-ignore - Dynamic import path
+    const module = await import(/* @vite-ignore */ filePath);
+
+    // Extract config object (could be default export or named export)
+    const config = module.default || module;
+
+    // If it's a function, call it
+    if (typeof config === 'function') {
+      return await config();
+    }
+
+    return config;
+  } catch (error) {
+    console.warn(
+      `[vite-plugin-config] Failed to load config file: ${filePath}`,
+      error
+    );
+    return {};
+  }
+}

package/src/utils/scan-config-files.util.ts

@@ -0,0 +1,40 @@
+/**
+ * Scan Config Files Utility
+ *
+ * Scans and collects all .config.ts files based on the provided options.
+ */
+
+import { glob } from 'glob';
+import type { ViteConfigPluginOptions } from '@/interfaces/vite-config-plugin-options.interface';
+
+/**
+ * Scan and collect all .config.ts files
+ *
+ * @param options - Plugin options containing scan configuration
+ * @returns Array of absolute file paths to config files
+ */
+export async function scanConfigFiles(
+  options: ViteConfigPluginOptions
+): Promise<string[]> {
+  const {
+    configFilePattern = 'src/**/*.config.ts',
+    excludeDirs = ['node_modules', 'dist', 'build', '.git'],
+    root = process.cwd(),
+  } = options;
+
+  const patterns = Array.isArray(configFilePattern)
+    ? configFilePattern
+    : [configFilePattern];
+  const configFiles: string[] = [];
+
+  for (const pattern of patterns) {
+    const files = await glob(pattern, {
+      cwd: root,
+      absolute: true,
+      ignore: excludeDirs.map((dir) => `**/${dir}/**`),
+    });
+    configFiles.push(...files);
+  }
+
+  return configFiles;
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "extends": "@nesvel/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    /* Silence TypeScript deprecation warnings */
+    "ignoreDeprecations": "6.0",
+    /* Module resolution - Override Nesvel's NodeNext for compatibility */
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    /* Decorators - Required for DI container */
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    /* Build options */
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "jsx": "react-jsx",
+    /* Testing */
+    "types": ["vitest/globals", "node"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*", "__tests__/**/*"],
+  "exclude": ["node_modules", "dist", "config"]
+}