@abdokouta/react-config 1.0.0 → 1.0.1

package/src/constants/tokens.constant.ts

@@ -1,12 +1,12 @@
 /**
  * Dependency Injection Tokens
- * 
+ *
  * Used for injecting configuration dependencies.
  */
 
 /**
  * Configuration driver token
- * 
+ *
  * @example
  * ```typescript
  * @Inject(CONFIG_DRIVER)
@@ -17,7 +17,7 @@ export const CONFIG_DRIVER = Symbol('CONFIG_DRIVER');
 
 /**
  * Configuration options token
- * 
+ *
  * @example
  * ```typescript
  * @Inject(CONFIG_OPTIONS)
@@ -28,7 +28,7 @@ export const CONFIG_OPTIONS = Symbol('CONFIG_OPTIONS');
 
 /**
  * Configuration service token
- * 
+ *
  * @example
  * ```typescript
  * @Inject(CONFIG_SERVICE)

package/src/drivers/env.driver.ts

@@ -3,7 +3,7 @@ import { getNestedValue, hasNestedValue } from '../utils/get-nested-value.util';
 
 /**
  * Environment Variable Configuration Driver
- * 
+ *
  * Loads configuration from environment variables (process.env).
  * Supports .env files via dotenv.
  */
@@ -44,26 +44,40 @@ export class EnvDriver implements ConfigDriver {
     // Try to load from custom global variable first (browser environment)
     if (typeof window !== 'undefined' && (window as any)[globalName]) {
       this.config = { ...(window as any)[globalName] };
-      console.log(`[EnvDriver] Loaded config from window.${globalName}:`, Object.keys(this.config).length, 'keys');
+      console.log(
+        `[EnvDriver] Loaded config from window.${globalName}:`,
+        Object.keys(this.config).length,
+        'keys'
+      );
     }
     // Fallback to process.env (Node.js environment or backward compatibility)
     else if (typeof process !== 'undefined' && process.env) {
       this.config = { ...process.env };
-      console.log('[EnvDriver] Loaded config from process.env:', Object.keys(this.config).length, 'keys');
+      console.log(
+        '[EnvDriver] Loaded config from process.env:',
+        Object.keys(this.config).length,
+        'keys'
+      );
     }
     // No config source available
     else {
-      console.warn('[EnvDriver] No config source available (neither window.' + globalName + ' nor process.env)');
+      console.warn(
+        '[EnvDriver] No config source available (neither window.' + globalName + ' nor process.env)'
+      );
       this.config = {};
     }
 
-    console.log('[EnvDriver] Initial config keys:', [...Object.keys(this.config).filter(k => k.includes('APP') || k.includes('VITE'))]);
+    console.log('[EnvDriver] Initial config keys:', [
+      ...Object.keys(this.config).filter((k) => k.includes('APP') || k.includes('VITE')),
+    ]);
 
     // Strip prefix if configured
     if (this.options.envPrefix !== false) {
       console.log('[EnvDriver] Stripping prefix...');
       this.stripPrefix();
-      console.log('[EnvDriver] After stripPrefix, config keys:', [...Object.keys(this.config).filter(k => k.includes('APP') || k.includes('VITE'))]);
+      console.log('[EnvDriver] After stripPrefix, config keys:', [
+        ...Object.keys(this.config).filter((k) => k.includes('APP') || k.includes('VITE')),
+      ]);
     }
 
     // Expand variables if enabled
@@ -159,12 +173,12 @@ export class EnvDriver implements ConfigDriver {
     // Auto-detect framework prefix
     if (prefix === 'auto' || prefix === undefined) {
       // Check for Vite (import.meta.env exists or VITE_ variables present)
-      const hasViteVars = Object.keys(this.config).some(key => key.startsWith('VITE_'));
+      const hasViteVars = Object.keys(this.config).some((key) => key.startsWith('VITE_'));
       if (hasViteVars || typeof import.meta !== 'undefined') {
         prefix = 'VITE_';
       }
       // Check for Next.js (NEXT_PUBLIC_ variables present)
-      else if (Object.keys(this.config).some(key => key.startsWith('NEXT_PUBLIC_'))) {
+      else if (Object.keys(this.config).some((key) => key.startsWith('NEXT_PUBLIC_'))) {
         prefix = 'NEXT_PUBLIC_';
       }
       // No framework detected, don't strip
@@ -176,7 +190,7 @@ export class EnvDriver implements ConfigDriver {
     // Strip the prefix from all matching keys
     if (typeof prefix === 'string' && prefix.length > 0) {
       const newConfig: Record<string, any> = {};
-      
+
       for (const [key, value] of Object.entries(this.config)) {
         if (key.startsWith(prefix)) {
           // Add both prefixed and unprefixed versions
@@ -187,7 +201,7 @@ export class EnvDriver implements ConfigDriver {
           newConfig[key] = value;
         }
       }
-      
+
       this.config = newConfig;
     }
   }

package/src/drivers/file.driver.ts

@@ -3,10 +3,10 @@ import { getNestedValue, hasNestedValue } from '@/utils/get-nested-value.util';
 
 /**
  * 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
  */
 export class FileDriver implements ConfigDriver {
@@ -35,13 +35,14 @@ export class FileDriver implements ConfigDriver {
     }
 
     // If running on server (Node.js), throw error
-    const isServer = typeof globalThis !== 'undefined' && 
-                     typeof (globalThis as typeof globalThis & { window?: any }).window === 'undefined';
-    
+    const isServer =
+      typeof globalThis !== 'undefined' &&
+      typeof (globalThis as typeof globalThis & { window?: any }).window === 'undefined';
+
     if (isServer) {
       throw new Error(
         'FileDriver requires pre-loaded configuration. ' +
-        'Use Vite plugin for client-side or pass config in constructor for server-side.'
+          'Use Vite plugin for client-side or pass config in constructor for server-side.'
       );
     }
 

package/src/index.ts

@@ -88,5 +88,6 @@ export type { ViteConfigPluginOptions } from './interfaces/vite-config-plugin-op
 // ============================================================================
 // Utilities
 // ============================================================================
+export { defineConfig } from './utils/define-config.util';
 export { getNestedValue, hasNestedValue } from './utils/get-nested-value.util';
 export { loadConfigFile } from './utils/load-config-file.util';

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

@@ -1,6 +1,6 @@
 /**
  * Configuration Driver Interface
- * 
+ *
  * Defines the contract for configuration drivers (env, file, firebase, etc.)
  */
 export interface ConfigDriver {

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

@@ -1,6 +1,6 @@
 /**
  * Configuration Service Interface
- * 
+ *
  * Defines the contract for configuration service implementations.
  */
 export interface ConfigServiceInterface {

package/src/plugins/vite.plugin.ts

@@ -3,26 +3,26 @@
  *
  * 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 })
@@ -40,7 +40,7 @@ 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.
  */
@@ -67,7 +67,7 @@ export function viteConfigPlugin(options: ViteConfigPluginOptions = {}): Plugin
         });
 
         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);
@@ -96,7 +96,10 @@ export function viteConfigPlugin(options: ViteConfigPluginOptions = {}): Plugin
 
       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] 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

package/src/services/config.service.ts

@@ -1,8 +1,8 @@
-import { Inject, Injectable } from "@abdokouta/react-di";
+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";
+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
@@ -29,7 +29,7 @@ import type { ConfigServiceInterface } from "@/interfaces/config-service.interfa
 export class ConfigService implements ConfigServiceInterface {
   constructor(
     @Inject(CONFIG_DRIVER)
-    private driver: ConfigDriver,
+    private driver: ConfigDriver
   ) {}
 
   /**
@@ -97,10 +97,10 @@ export class ConfigService implements ConfigServiceInterface {
     if (value === undefined) {
       return undefined;
     }
-    if (typeof value === "boolean") {
+    if (typeof value === 'boolean') {
       return value;
     }
-    return ["true", "1", "yes", "on"].includes(String(value).toLowerCase());
+    return ['true', '1', 'yes', 'on'].includes(String(value).toLowerCase());
   }
 
   /**
@@ -126,7 +126,7 @@ export class ConfigService implements ConfigServiceInterface {
       return value.map(String);
     }
     return String(value)
-      .split(",")
+      .split(',')
       .map((v) => v.trim())
       .filter(Boolean);
   }
@@ -139,7 +139,7 @@ export class ConfigService implements ConfigServiceInterface {
     if (value === undefined) {
       return undefined;
     }
-    if (typeof value === "object") {
+    if (typeof value === 'object') {
       return value as T;
     }
     try {

package/src/utils/define-config.util.ts

@@ -0,0 +1,35 @@
+/**
+ * Define Config Utility
+ *
+ * Helper function to define config module options with type safety.
+ *
+ * @module @abdokouta/config
+ */
+
+import type { ConfigModuleOptions } from '../interfaces/config-module-options.interface';
+
+/**
+ * Helper function to define config module options with type safety
+ *
+ * Provides IDE autocomplete and type checking for configuration objects.
+ * This pattern is consistent with modern tooling (Vite, Vitest, etc.).
+ *
+ * @param config - The config module options object
+ * @returns The same configuration object with proper typing
+ *
+ * @example
+ * ```typescript
+ * // config.config.ts
+ * import { defineConfig } from '@abdokouta/config';
+ *
+ * export default defineConfig({
+ *   driver: 'env',
+ *   ignoreEnvFile: true,
+ *   isGlobal: true,
+ *   envPrefix: 'auto',
+ * });
+ * ```
+ */
+export function defineConfig(config: ConfigModuleOptions): ConfigModuleOptions {
+  return config;
+}

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

@@ -1,11 +1,11 @@
 /**
  * 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' } };
@@ -33,15 +33,12 @@ export function getNestedValue<T = any>(
 
 /**
  * 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 {
+export function hasNestedValue(obj: Record<string, any>, path: string): boolean {
   const keys = path.split('.');
   let current: any = obj;
 

package/src/utils/index.ts

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

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

@@ -10,9 +10,7 @@
  * @param filePath - Absolute path to the config file
  * @returns Parsed config object
  */
-export async function loadConfigFile(
-  filePath: string
-): Promise<Record<string, any>> {
+export async function loadConfigFile(filePath: string): Promise<Record<string, any>> {
   try {
     // Dynamic import of the config file
     // @ts-ignore - Dynamic import path
@@ -28,10 +26,7 @@ export async function loadConfigFile(
 
     return config;
   } catch (error) {
-    console.warn(
-      `[vite-plugin-config] Failed to load config file: ${filePath}`,
-      error
-    );
+    console.warn(`[vite-plugin-config] Failed to load config file: ${filePath}`, error);
     return {};
   }
 }

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

@@ -13,18 +13,14 @@ import type { ViteConfigPluginOptions } from '@/interfaces/vite-config-plugin-op
  * @param options - Plugin options containing scan configuration
  * @returns Array of absolute file paths to config files
  */
-export async function scanConfigFiles(
-  options: ViteConfigPluginOptions
-): Promise<string[]> {
+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 patterns = Array.isArray(configFilePattern) ? configFilePattern : [configFilePattern];
   const configFiles: string[] = [];
 
   for (const pattern of patterns) {

package/tsup.config.ts

@@ -1,4 +1,4 @@
-import { defineConfig } from "tsup";
+import { defineConfig } from 'tsup';
 
 /**
  * tsup Configuration for @abdokouta/logger Package
@@ -15,7 +15,7 @@ export default defineConfig({
    *
    * Exports the logger service, transporters, formatters, and hooks.
    */
-  entry: ["src/index.ts"],
+  entry: ['src/index.ts'],
 
   /**
    * Dual format output (ESM + CJS).
@@ -23,7 +23,7 @@ export default defineConfig({
    * - ESM: Modern module format for tree-shaking
    * - CJS: CommonJS for Node.js compatibility
    */
-  format: ["esm", "cjs"],
+  format: ['esm', 'cjs'],
 
   /**
    * Generate TypeScript declaration files.
@@ -60,14 +60,14 @@ export default defineConfig({
    * Supports modern browsers and Node.js 14+.
    * Includes optional chaining, nullish coalescing, and other ES2020 features.
    */
-  target: "es2020",
+  target: 'es2020',
 
   /**
    * Platform-neutral build.
    *
    * Works in both browser and Node.js environments.
    */
-  platform: "neutral",
+  platform: 'neutral',
 
   /**
    * External dependencies that should not be bundled.
@@ -75,7 +75,7 @@ export default defineConfig({
    * - @abdokouta/react-di: DI system (peer dependency)
    * - react: React library (optional peer dependency for hooks)
    */
-  external: ["@abdokouta/react-di", "react"],
+  external: ['@abdokouta/react-di', 'react'],
 
   /**
    * Disable code splitting for library builds.
@@ -100,6 +100,6 @@ export default defineConfig({
    * This ensures proper module resolution in all environments.
    */
   outExtension({ format }) {
-    return { js: format === "esm" ? ".mjs" : ".js" };
+    return { js: format === 'esm' ? '.mjs' : '.js' };
   },
 });

package/vitest.config.ts

@@ -15,9 +15,9 @@
  * @category Configuration
  */
 
-import { fileURLToPath } from "url";
-import { resolve, dirname } from "path";
-import { defineConfig } from "vitest/config";
+import { fileURLToPath } from 'url';
+import { resolve, dirname } from 'path';
+import { defineConfig } from 'vitest/config';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -28,30 +28,30 @@ export default defineConfig({
     globals: true,
 
     // Use jsdom environment for React testing
-    environment: "jsdom",
+    environment: 'jsdom',
 
     // Run setup file before tests
-    setupFiles: ["./__tests__/vitest.setup.ts"],
+    setupFiles: ['./__tests__/vitest.setup.ts'],
 
     // Only include __tests__ directory
-    include: ["__tests__/**/*.{test,spec}.{ts,tsx}"],
+    include: ['__tests__/**/*.{test,spec}.{ts,tsx}'],
 
     // Coverage configuration
     coverage: {
       // Use v8 coverage provider (faster than istanbul)
-      provider: "v8",
+      provider: 'v8',
 
       // Generate multiple report formats
-      reporter: ["text", "json", "html"],
+      reporter: ['text', 'json', 'html'],
 
       // Exclude files from coverage
       exclude: [
-        "node_modules/",
-        "dist/",
-        "test/",
-        "**/*.test.ts",
-        "**/*.test.tsx",
-        "**/*.config.ts",
+        'node_modules/',
+        'dist/',
+        'test/',
+        '**/*.test.ts',
+        '**/*.test.tsx',
+        '**/*.config.ts',
       ],
     },
   },
@@ -60,7 +60,7 @@ export default defineConfig({
   resolve: {
     alias: {
       // Map @ to ./src for consistent imports
-      "@": resolve(__dirname, "./src"),
+      '@': resolve(__dirname, './src'),
     },
   },
 });