@abdokouta/react-config 1.0.0 → 1.0.1

package/__tests__/services/config.service.test.ts

@@ -1,22 +1,22 @@
 /**
  * @fileoverview Tests for ConfigService
- * 
+ *
  * This test suite verifies the ConfigService functionality including:
  * - Getting configuration values
  * - Type-safe getters (getString, getNumber, getBoolean)
  * - Throwing methods (getOrThrow, getStringOrThrow)
  * - Default value handling
  * - Nested key access
- * 
+ *
  * @module @abdokouta/config
  * @category Tests
  */
 
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { ConfigService } from "@/services/config.service";
-import type { ConfigDriver } from "@/interfaces/config-driver.interface";
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ConfigService } from '@/services/config.service';
+import type { ConfigDriver } from '@/interfaces/config-driver.interface';
 
-describe("ConfigService", () => {
+describe('ConfigService', () => {
   let mockDriver: ConfigDriver;
   let configService: ConfigService;
 
@@ -25,52 +25,59 @@ describe("ConfigService", () => {
     mockDriver = {
       load: vi.fn().mockReturnValue({
         app: {
-          name: "Test App",
+          name: 'Test App',
           port: 3000,
           debug: true,
         },
         database: {
-          host: "localhost",
+          host: 'localhost',
           port: 5432,
-          name: "testdb",
+          name: 'testdb',
         },
         api: {
-          key: "test-key-123",
+          key: 'test-key-123',
           timeout: 5000,
         },
       }),
       get: vi.fn((key: string, defaultValue?: any) => {
         const data: any = {
-          "app.name": "Test App",
-          "app.port": 3000,
-          "app.debug": true,
-          "database.host": "localhost",
-          "database.port": 5432,
-          "api.key": "test-key-123",
+          'app.name': 'Test App',
+          'app.port': 3000,
+          'app.debug': true,
+          'database.host': 'localhost',
+          'database.port': 5432,
+          'api.key': 'test-key-123',
         };
         return data[key] ?? defaultValue;
       }),
       has: vi.fn((key: string) => {
-        const keys = ["app.name", "app.port", "app.debug", "database.host", "database.port", "api.key"];
+        const keys = [
+          'app.name',
+          'app.port',
+          'app.debug',
+          'database.host',
+          'database.port',
+          'api.key',
+        ];
         return keys.includes(key);
       }),
       all: vi.fn().mockReturnValue({
-        app: { name: "Test App", port: 3000, debug: true },
-        database: { host: "localhost", port: 5432, name: "testdb" },
+        app: { name: 'Test App', port: 3000, debug: true },
+        database: { host: 'localhost', port: 5432, name: 'testdb' },
       }),
     };
 
     configService = new ConfigService(mockDriver);
   });
 
-  describe("get", () => {
-    it("should get existing configuration value", () => {
+  describe('get', () => {
+    it('should get existing configuration value', () => {
       // Act: Get config value
-      const appName = configService.get("app.name");
+      const appName = configService.get('app.name');
 
       // Assert: Value is returned
-      expect(appName).toBe("Test App");
-      expect(mockDriver.get).toHaveBeenCalledWith("app.name", undefined);
+      expect(appName).toBe('Test App');
+      expect(mockDriver.get).toHaveBeenCalledWith('app.name', undefined);
     });
 
     it("should return default value when key doesn't exist", () => {
@@ -78,10 +85,10 @@ describe("ConfigService", () => {
       mockDriver.get = vi.fn((key, defaultValue) => defaultValue);
 
       // Act: Get with default
-      const value = configService.get("missing.key", "default");
+      const value = configService.get('missing.key', 'default');
 
       // Assert: Default is returned
-      expect(value).toBe("default");
+      expect(value).toBe('default');
     });
 
     it("should return undefined when key doesn't exist and no default", () => {
@@ -89,46 +96,46 @@ describe("ConfigService", () => {
       mockDriver.get = vi.fn(() => undefined);
 
       // Act: Get without default
-      const value = configService.get("missing.key");
+      const value = configService.get('missing.key');
 
       // Assert: Undefined is returned
       expect(value).toBeUndefined();
     });
 
-    it("should handle nested keys", () => {
+    it('should handle nested keys', () => {
       // Act: Get nested value
-      const dbHost = configService.get("database.host");
+      const dbHost = configService.get('database.host');
 
       // Assert: Nested value is returned
-      expect(dbHost).toBe("localhost");
+      expect(dbHost).toBe('localhost');
     });
 
-    it("should handle numeric values", () => {
+    it('should handle numeric values', () => {
       // Act: Get numeric value
-      const port = configService.get<number>("app.port");
+      const port = configService.get<number>('app.port');
 
       // Assert: Number is returned
       expect(port).toBe(3000);
-      expect(typeof port).toBe("number");
+      expect(typeof port).toBe('number');
     });
 
-    it("should handle boolean values", () => {
+    it('should handle boolean values', () => {
       // Act: Get boolean value
-      const debug = configService.get<boolean>("app.debug");
+      const debug = configService.get<boolean>('app.debug');
 
       // Assert: Boolean is returned
       expect(debug).toBe(true);
-      expect(typeof debug).toBe("boolean");
+      expect(typeof debug).toBe('boolean');
     });
   });
 
-  describe("getOrThrow", () => {
-    it("should return value when key exists", () => {
+  describe('getOrThrow', () => {
+    it('should return value when key exists', () => {
       // Act: Get existing key
-      const appName = configService.getOrThrow("app.name");
+      const appName = configService.getOrThrow('app.name');
 
       // Assert: Value is returned
-      expect(appName).toBe("Test App");
+      expect(appName).toBe('Test App');
     });
 
     it("should throw error when key doesn't exist", () => {
@@ -137,29 +144,29 @@ describe("ConfigService", () => {
 
       // Act & Assert: Should throw
       expect(() => {
-        configService.getOrThrow("missing.key");
+        configService.getOrThrow('missing.key');
       }).toThrow();
     });
 
-    it("should throw with descriptive error message", () => {
+    it('should throw with descriptive error message', () => {
       // Arrange: Mock missing key
       mockDriver.get = vi.fn(() => undefined);
 
       // Act & Assert: Should throw with message
       expect(() => {
-        configService.getOrThrow("missing.key");
+        configService.getOrThrow('missing.key');
       }).toThrow(/missing\.key/);
     });
   });
 
-  describe("getString", () => {
-    it("should return string value", () => {
+  describe('getString', () => {
+    it('should return string value', () => {
       // Act: Get string
-      const appName = configService.getString("app.name");
+      const appName = configService.getString('app.name');
 
       // Assert: String is returned
-      expect(appName).toBe("Test App");
-      expect(typeof appName).toBe("string");
+      expect(appName).toBe('Test App');
+      expect(typeof appName).toBe('string');
     });
 
     it("should return default string when key doesn't exist", () => {
@@ -167,32 +174,32 @@ describe("ConfigService", () => {
       mockDriver.get = vi.fn((key, defaultValue) => defaultValue);
 
       // Act: Get with default
-      const value = configService.getString("missing.key", "default");
+      const value = configService.getString('missing.key', 'default');
 
       // Assert: Default is returned
-      expect(value).toBe("default");
+      expect(value).toBe('default');
     });
 
-    it("should return undefined when no default provided", () => {
+    it('should return undefined when no default provided', () => {
       // Arrange: Mock missing key
       mockDriver.get = vi.fn(() => undefined);
 
       // Act: Get without default
-      const value = configService.getString("missing.key");
+      const value = configService.getString('missing.key');
 
       // Assert: Undefined is returned
       expect(value).toBeUndefined();
     });
   });
 
-  describe("getStringOrThrow", () => {
-    it("should return string value when key exists", () => {
+  describe('getStringOrThrow', () => {
+    it('should return string value when key exists', () => {
       // Act: Get existing string
-      const apiKey = configService.getStringOrThrow("api.key");
+      const apiKey = configService.getStringOrThrow('api.key');
 
       // Assert: String is returned
-      expect(apiKey).toBe("test-key-123");
-      expect(typeof apiKey).toBe("string");
+      expect(apiKey).toBe('test-key-123');
+      expect(typeof apiKey).toBe('string');
     });
 
     it("should throw when key doesn't exist", () => {
@@ -201,19 +208,19 @@ describe("ConfigService", () => {
 
       // Act & Assert: Should throw
       expect(() => {
-        configService.getStringOrThrow("missing.key");
+        configService.getStringOrThrow('missing.key');
       }).toThrow();
     });
   });
 
-  describe("getNumber", () => {
-    it("should return number value", () => {
+  describe('getNumber', () => {
+    it('should return number value', () => {
       // Act: Get number
-      const port = configService.getNumber("app.port");
+      const port = configService.getNumber('app.port');
 
       // Assert: Number is returned
       expect(port).toBe(3000);
-      expect(typeof port).toBe("number");
+      expect(typeof port).toBe('number');
     });
 
     it("should return default number when key doesn't exist", () => {
@@ -221,67 +228,67 @@ describe("ConfigService", () => {
       mockDriver.get = vi.fn((key, defaultValue) => defaultValue);
 
       // Act: Get with default
-      const value = configService.getNumber("missing.key", 8080);
+      const value = configService.getNumber('missing.key', 8080);
 
       // Assert: Default is returned
       expect(value).toBe(8080);
     });
 
-    it("should parse string numbers", () => {
+    it('should parse string numbers', () => {
       // Arrange: Mock string number
-      mockDriver.get = vi.fn(() => "5432");
+      mockDriver.get = vi.fn(() => '5432');
 
       // Act: Get as number
-      const port = configService.getNumber("database.port");
+      const port = configService.getNumber('database.port');
 
       // Assert: Parsed number is returned
       expect(port).toBe(5432);
-      expect(typeof port).toBe("number");
+      expect(typeof port).toBe('number');
     });
   });
 
-  describe("getBoolean", () => {
-    it("should return boolean value", () => {
+  describe('getBoolean', () => {
+    it('should return boolean value', () => {
       // Act: Get boolean
-      const debug = configService.getBoolean("app.debug");
+      const debug = configService.getBoolean('app.debug');
 
       // Assert: Boolean is returned
       expect(debug).toBe(true);
-      expect(typeof debug).toBe("boolean");
+      expect(typeof debug).toBe('boolean');
     });
 
-    it("should parse string booleans", () => {
+    it('should parse string booleans', () => {
       // Arrange: Mock string boolean
       mockDriver.get = vi.fn((key) => {
-        if (key === "feature.enabled") return "true";
-        if (key === "feature.disabled") return "false";
+        if (key === 'feature.enabled') return 'true';
+        if (key === 'feature.disabled') return 'false';
         return undefined;
       });
 
       // Act: Get as boolean
-      const enabled = configService.getBoolean("feature.enabled");
-      const disabled = configService.getBoolean("feature.disabled");
+      const enabled = configService.getBoolean('feature.enabled');
+      const disabled = configService.getBoolean('feature.disabled');
 
       // Assert: Parsed booleans are returned
       expect(enabled).toBe(true);
       expect(disabled).toBe(false);
     });
 
-    it("should handle truthy/falsy values", () => {
+    it('should handle truthy/falsy values', () => {
       // Arrange: Mock various values
       mockDriver.get = vi.fn((key) => {
-        if (key === "one") return 1;
-        if (key === "zero") return 0;
-        if (key === "yes") return "yes";
-        if (key === "no") return "no";
+        if (key === 'one') return 1;
+        if (key === 'zero') return 0;
+        if (key === 'yes') return 'yes';
+        if (key === 'no') return 'no';
         return undefined;
       });
 
       // Act: Get as booleans
-      const one = configService.getBoolean("one");
-      const zero = configService.getBoolean("zero");
-      const yes = configService.getBoolean("yes");
-      const no = configService.getBoolean("no");
+      const one = configService.getBoolean('one');
+      const zero = configService.getBoolean('zero');
+      const yes = configService.getBoolean('yes');
+      const no = configService.getBoolean('no');
 
       // Assert: Values are converted to boolean
       expect(one).toBe(true);
@@ -291,35 +298,35 @@ describe("ConfigService", () => {
     });
   });
 
-  describe("Edge Cases", () => {
-    it("should handle null values", () => {
+  describe('Edge Cases', () => {
+    it('should handle null values', () => {
       // Arrange: Mock null value
       mockDriver.get = vi.fn(() => null);
 
       // Act: Get null value
-      const value = configService.get("null.key");
+      const value = configService.get('null.key');
 
       // Assert: Null is returned
       expect(value).toBeNull();
     });
 
-    it("should handle empty string values", () => {
+    it('should handle empty string values', () => {
       // Arrange: Mock empty string
-      mockDriver.get = vi.fn(() => "");
+      mockDriver.get = vi.fn(() => '');
 
       // Act: Get empty string
-      const value = configService.getString("empty.key");
+      const value = configService.getString('empty.key');
 
       // Assert: Empty string is returned
-      expect(value).toBe("");
+      expect(value).toBe('');
     });
 
-    it("should handle zero values", () => {
+    it('should handle zero values', () => {
       // Arrange: Mock zero
       mockDriver.get = vi.fn(() => 0);
 
       // Act: Get zero
-      const value = configService.getNumber("zero.key");
+      const value = configService.getNumber('zero.key');
 
       // Assert: Zero is returned
       expect(value).toBe(0);

package/__tests__/setup.d.ts

@@ -1,11 +1,11 @@
 /**
  * @fileoverview Type declarations for Vitest test environment
- * 
+ *
  * This file extends Vitest's type definitions to include custom matchers
  * and global test utilities.
- * 
+ *
  * @module @abdokouta/config
  * @category Configuration
  */
 
-import "vitest/globals";
+import 'vitest/globals';

package/__tests__/vitest.setup.ts

@@ -1,26 +1,26 @@
 /**
  * @fileoverview Vitest setup file for @abdokouta/config package
- * 
+ *
  * This file configures the testing environment before running tests.
  * It sets up container mocking for dependency injection tests.
- * 
+ *
  * Setup Features:
  * - Container mocking for DI tests
- * 
+ *
  * @module @abdokouta/config
  * @category Configuration
  */
 
-import { vi } from "vitest";
+import { vi } from 'vitest';
 
 /**
  * Mock @abdokouta/react-di decorators
- * 
+ *
  * This ensures that decorator metadata doesn't interfere with tests
  * and allows us to test module behavior in isolation.
  */
-vi.mock("@abdokouta/react-di", async () => {
-  const actual = await vi.importActual("@abdokouta/react-di");
+vi.mock('@abdokouta/react-di', async () => {
+  const actual = await vi.importActual('@abdokouta/react-di');
   return {
     ...actual,
     Injectable: () => (target: any) => target,

package/config/config.config.ts

@@ -1,39 +1,39 @@
 /**
  * Config Package Configuration
- * 
+ *
  * Configuration for the @abdokouta/config package.
  * Defines how environment variables are loaded and accessed.
- * 
+ *
  * @module config/config
  */
 
-import type { ConfigModuleOptions } from '@abdokouta/config';
+import { defineConfig } from '@abdokouta/config';
 
 /**
  * Config Configuration
- * 
+ *
  * Settings:
  * - driver: 'env' (reads from process.env)
  * - ignoreEnvFile: true (don't load .env file in browser)
  * - isGlobal: true (available to all modules)
  * - envPrefix: 'auto' (auto-detect and strip VITE_ or NEXT_PUBLIC_ prefix)
- * 
+ *
  * With envPrefix: 'auto', you can access:
  * - VITE_APP_NAME as APP_NAME
  * - NEXT_PUBLIC_API_URL as API_URL
- * 
+ *
  * @example
  * ```typescript
  * // In app.module.ts
  * import { configConfig } from '@/config/config.config';
- * 
+ *
  * @Module({
  *   imports: [ConfigModule.forRoot(configConfig)],
  * })
  * export class AppModule {}
  * ```
  */
-export const configConfig: ConfigModuleOptions = {
+export const configConfig = defineConfig({
   /**
    * Driver to use for loading configuration
    * 'env' reads from process.env
@@ -59,4 +59,4 @@ export const configConfig: ConfigModuleOptions = {
    * So VITE_APP_NAME becomes accessible as APP_NAME
    */
   envPrefix: 'auto',
-};
+});

package/dist/index.d.mts

@@ -433,6 +433,38 @@ interface ViteConfigPluginOptions {
     globalName?: string;
 }
 
+/**
+ * Define Config Utility
+ *
+ * Helper function to define config module options with type safety.
+ *
+ * @module @abdokouta/config
+ */
+
+/**
+ * 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',
+ * });
+ * ```
+ */
+declare function defineConfig(config: ConfigModuleOptions): ConfigModuleOptions;
+
 /**
  * Get nested value from object using dot notation
  *
@@ -471,4 +503,4 @@ declare function hasNestedValue(obj: Record<string, any>, path: string): boolean
  */
 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 };
+export { type ConfigDriver, ConfigModule, type ConfigModuleOptions, ConfigService, type ConfigServiceInterface, EnvDriver, FileDriver, type ViteConfigPluginOptions, defineConfig, getNestedValue, hasNestedValue, loadConfigFile };

package/dist/index.d.ts

@@ -433,6 +433,38 @@ interface ViteConfigPluginOptions {
     globalName?: string;
 }
 
+/**
+ * Define Config Utility
+ *
+ * Helper function to define config module options with type safety.
+ *
+ * @module @abdokouta/config
+ */
+
+/**
+ * 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',
+ * });
+ * ```
+ */
+declare function defineConfig(config: ConfigModuleOptions): ConfigModuleOptions;
+
 /**
  * Get nested value from object using dot notation
  *
@@ -471,4 +503,4 @@ declare function hasNestedValue(obj: Record<string, any>, path: string): boolean
  */
 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 };
+export { type ConfigDriver, ConfigModule, type ConfigModuleOptions, ConfigService, type ConfigServiceInterface, EnvDriver, FileDriver, type ViteConfigPluginOptions, defineConfig, getNestedValue, hasNestedValue, loadConfigFile };