@riktajs/core 0.3.1 → 0.4.0-beta.2

package/README.md

@@ -97,6 +97,7 @@ Everything you need to build production-ready APIs.
 |-------|-------------|
 | [**Architecture**](./docs/guide/architecture.md) | How Rikta's auto-discovery works under the hood. |
 | [**Dependency Injection**](./docs/guide/dependency-injection.md) | Using `@Autowired`, tokens, and scopes. |
+| [**Configuration**](./docs/guide/configuration.md) | Type-safe configuration with .env and Zod validation. |
 | [**Routing**](./docs/guide/routing.md) | Controllers, methods, and parameter handling. |
 | [**Validation**](./docs/guide/validation.md) | **New!** Type-safe validation with Zod. |
 | [**Lifecycle**](./docs/guide/lifecycle.md) | Hooks (`OnProviderInit`) and the Event Bus. |

package/dist/core/config/abstract-config-provider.d.ts

@@ -0,0 +1,162 @@
+import { z, ZodSchema } from 'zod';
+/**
+ * Exception thrown when config validation fails
+ */
+export declare class ConfigValidationException extends Error {
+    readonly errors: z.ZodError;
+    constructor(errors: z.ZodError, providerName: string);
+}
+/**
+ * Abstract base class for configuration providers
+ *
+ * This class handles:
+ * - Loading .env files (base + environment-specific)
+ * - Validating environment variables against a Zod schema
+ * - Populating decorated properties with validated values
+ * - Caching validated configuration
+ *
+ * Child classes must:
+ * 1. Extend this class
+ * 2. Implement the abstract schema() method
+ * 3. Decorate properties with @ConfigProperty()
+ * 4. Call populate() in their constructor
+ *
+ * @example
+ * ```typescript
+ * import { AbstractConfigProvider, ProviderConfig, ConfigProperty } from '@riktajs/core';
+ * import { z } from 'zod';
+ *
+ * @ProviderConfig('APP_CONFIG')
+ * export class AppConfigProvider extends AbstractConfigProvider {
+ *   schema() {
+ *     return z.object({
+ *       PORT: z.coerce.number().int().min(1).max(65535),
+ *       HOST: z.string().default('localhost'),
+ *       NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+ *     });
+ *   }
+ *
+ *   @ConfigProperty()
+ *   port!: number;
+ *
+ *   @ConfigProperty()
+ *   host!: string;
+ *
+ *   @ConfigProperty('NODE_ENV')
+ *   environment!: 'development' | 'production' | 'test';
+ *
+ *   constructor() {
+ *     super();
+ *     this.populate();
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AbstractConfigProvider {
+    /**
+     * Cache for validated configuration
+     * Frozen to prevent accidental mutations
+     */
+    private _cache?;
+    /**
+     * Flag to track if .env files have been loaded
+     */
+    private static envLoaded;
+    /**
+     * Define the Zod schema for this configuration
+     *
+     * @returns A Zod schema that validates the environment variables
+     *
+     * @example
+     * ```typescript
+     * schema() {
+     *   return z.object({
+     *     DATABASE_URL: z.string().url(),
+     *     DB_POOL_SIZE: z.coerce.number().int().min(1).max(100).default(10),
+     *     DB_TIMEOUT: z.coerce.number().int().default(30000),
+     *   });
+     * }
+     * ```
+     */
+    protected abstract schema(): ZodSchema;
+    /**
+     * Constructor loads .env files if not already loaded
+     */
+    constructor();
+    /**
+     * Load .env files with environment-specific precedence
+     *
+     * Loading order (later files override earlier):
+     * 1. .env (base configuration)
+     * 2. .env.{NODE_ENV} (environment-specific)
+     *
+     * @private
+     */
+    private loadEnvFiles;
+    /**
+     * Validate and cache the configuration
+     *
+     * This method runs the Zod schema validation against process.env
+     * and caches the result. Subsequent calls return the cached value.
+     *
+     * @returns The validated and frozen configuration object
+     * @throws {ConfigValidationException} If validation fails
+     *
+     * @private
+     */
+    private validateAndCache;
+    /**
+     * Populate decorated properties with validated values
+     *
+     * This method reads the @ConfigProperty metadata and assigns
+     * the corresponding validated environment values to class properties.
+     *
+     * Must be called in the child class constructor after super().
+     *
+     * @throws {ConfigValidationException} If validation fails
+     *
+     * @example
+     * ```typescript
+     * constructor() {
+     *   super();
+     *   this.populate(); // Must call this!
+     * }
+     * ```
+     */
+    protected populate(): void;
+    /**
+     * Get the raw validated configuration object
+     *
+     * This is useful for accessing config values that aren't mapped
+     * to properties, or for passing the entire config to other services.
+     *
+     * @returns The validated and frozen configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = this.getConfig();
+     * console.log('All env vars:', config);
+     * ```
+     */
+    protected getConfig(): Readonly<Record<string, unknown>>;
+    /**
+     * Get a specific configuration value by key
+     *
+     * @param key - The environment variable name
+     * @returns The validated value, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const port = this.get<number>('PORT');
+     * const apiKey = this.get<string>('API_KEY');
+     * ```
+     */
+    protected get<T = unknown>(key: string): T | undefined;
+    /**
+     * Reset the env loaded flag (for testing)
+     *
+     * @internal
+     */
+    static resetEnvLoaded(): void;
+}
+//# sourceMappingURL=abstract-config-provider.d.ts.map

package/dist/core/config/abstract-config-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-config-provider.d.ts","sourceRoot":"","sources":["../../../src/core/config/abstract-config-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAMnC;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;aAEhC,MAAM,EAAE,CAAC,CAAC,QAAQ;gBAAlB,MAAM,EAAE,CAAC,CAAC,QAAQ,EAClC,YAAY,EAAE,MAAM;CAYvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,8BAAsB,sBAAsB;IAC1C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,CAAoC;IAEnD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS,CAAS;IAEjC;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,IAAI,SAAS;IAEtC;;OAEG;;IAQH;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAiBpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,QAAQ,IAAI,IAAI;IAgB1B;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,SAAS,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIxD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKtD;;;;OAIG;IACH,MAAM,CAAC,cAAc,IAAI,IAAI;CAG9B"}

package/dist/core/config/abstract-config-provider.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractConfigProvider = exports.ConfigValidationException = void 0;
+const zod_1 = require("zod");
+const dotenv_1 = require("dotenv");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const config_property_decorator_1 = require("../decorators/config-property.decorator");
+/**
+ * Exception thrown when config validation fails
+ */
+class ConfigValidationException extends Error {
+    errors;
+    constructor(errors, providerName) {
+        const errorMessages = errors.errors
+            .map(err => `  - ${err.path.join('.')}: ${err.message}`)
+            .join('\n');
+        super(`Configuration validation failed for ${providerName}:\n${errorMessages}\n\n` +
+            `Please check your .env file and ensure all required variables are set correctly.`);
+        this.errors = errors;
+        this.name = 'ConfigValidationException';
+    }
+}
+exports.ConfigValidationException = ConfigValidationException;
+/**
+ * Abstract base class for configuration providers
+ *
+ * This class handles:
+ * - Loading .env files (base + environment-specific)
+ * - Validating environment variables against a Zod schema
+ * - Populating decorated properties with validated values
+ * - Caching validated configuration
+ *
+ * Child classes must:
+ * 1. Extend this class
+ * 2. Implement the abstract schema() method
+ * 3. Decorate properties with @ConfigProperty()
+ * 4. Call populate() in their constructor
+ *
+ * @example
+ * ```typescript
+ * import { AbstractConfigProvider, ProviderConfig, ConfigProperty } from '@riktajs/core';
+ * import { z } from 'zod';
+ *
+ * @ProviderConfig('APP_CONFIG')
+ * export class AppConfigProvider extends AbstractConfigProvider {
+ *   schema() {
+ *     return z.object({
+ *       PORT: z.coerce.number().int().min(1).max(65535),
+ *       HOST: z.string().default('localhost'),
+ *       NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+ *     });
+ *   }
+ *
+ *   @ConfigProperty()
+ *   port!: number;
+ *
+ *   @ConfigProperty()
+ *   host!: string;
+ *
+ *   @ConfigProperty('NODE_ENV')
+ *   environment!: 'development' | 'production' | 'test';
+ *
+ *   constructor() {
+ *     super();
+ *     this.populate();
+ *   }
+ * }
+ * ```
+ */
+class AbstractConfigProvider {
+    /**
+     * Cache for validated configuration
+     * Frozen to prevent accidental mutations
+     */
+    _cache;
+    /**
+     * Flag to track if .env files have been loaded
+     */
+    static envLoaded = false;
+    /**
+     * Constructor loads .env files if not already loaded
+     */
+    constructor() {
+        if (!AbstractConfigProvider.envLoaded) {
+            this.loadEnvFiles();
+            AbstractConfigProvider.envLoaded = true;
+        }
+    }
+    /**
+     * Load .env files with environment-specific precedence
+     *
+     * Loading order (later files override earlier):
+     * 1. .env (base configuration)
+     * 2. .env.{NODE_ENV} (environment-specific)
+     *
+     * @private
+     */
+    loadEnvFiles() {
+        const env = process.env.NODE_ENV || 'development';
+        const cwd = process.cwd();
+        // Load base .env file
+        const baseEnvPath = (0, path_1.resolve)(cwd, '.env');
+        if ((0, fs_1.existsSync)(baseEnvPath)) {
+            (0, dotenv_1.config)({ path: baseEnvPath, override: false });
+        }
+        // Load environment-specific .env file (overrides base)
+        const envSpecificPath = (0, path_1.resolve)(cwd, `.env.${env}`);
+        if ((0, fs_1.existsSync)(envSpecificPath)) {
+            (0, dotenv_1.config)({ path: envSpecificPath, override: true });
+        }
+    }
+    /**
+     * Validate and cache the configuration
+     *
+     * This method runs the Zod schema validation against process.env
+     * and caches the result. Subsequent calls return the cached value.
+     *
+     * @returns The validated and frozen configuration object
+     * @throws {ConfigValidationException} If validation fails
+     *
+     * @private
+     */
+    validateAndCache() {
+        if (this._cache) {
+            return this._cache;
+        }
+        try {
+            const schema = this.schema();
+            const validated = schema.parse(process.env);
+            // Freeze the cache to make it immutable (tip from plan)
+            this._cache = Object.freeze(validated);
+            return this._cache;
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                throw new ConfigValidationException(error, this.constructor.name);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Populate decorated properties with validated values
+     *
+     * This method reads the @ConfigProperty metadata and assigns
+     * the corresponding validated environment values to class properties.
+     *
+     * Must be called in the child class constructor after super().
+     *
+     * @throws {ConfigValidationException} If validation fails
+     *
+     * @example
+     * ```typescript
+     * constructor() {
+     *   super();
+     *   this.populate(); // Must call this!
+     * }
+     * ```
+     */
+    populate() {
+        // Validate and get cached config
+        const config = this.validateAndCache();
+        // Get property mappings from metadata
+        const mappings = (0, config_property_decorator_1.getConfigPropertyMappings)(this.constructor);
+        // Assign values to properties
+        for (const mapping of mappings) {
+            const value = config[mapping.envKey];
+            // Use type assertion since we know the property exists
+            this[mapping.propertyKey] = value;
+        }
+    }
+    /**
+     * Get the raw validated configuration object
+     *
+     * This is useful for accessing config values that aren't mapped
+     * to properties, or for passing the entire config to other services.
+     *
+     * @returns The validated and frozen configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = this.getConfig();
+     * console.log('All env vars:', config);
+     * ```
+     */
+    getConfig() {
+        return this.validateAndCache();
+    }
+    /**
+     * Get a specific configuration value by key
+     *
+     * @param key - The environment variable name
+     * @returns The validated value, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const port = this.get<number>('PORT');
+     * const apiKey = this.get<string>('API_KEY');
+     * ```
+     */
+    get(key) {
+        const config = this.validateAndCache();
+        return config[key];
+    }
+    /**
+     * Reset the env loaded flag (for testing)
+     *
+     * @internal
+     */
+    static resetEnvLoaded() {
+        AbstractConfigProvider.envLoaded = false;
+    }
+}
+exports.AbstractConfigProvider = AbstractConfigProvider;
+//# sourceMappingURL=abstract-config-provider.js.map

package/dist/core/config/abstract-config-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-config-provider.js","sourceRoot":"","sources":["../../../src/core/config/abstract-config-provider.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export * from './abstract-config-provider';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}

package/dist/core/config/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./abstract-config-provider"), exports);
+//# sourceMappingURL=index.js.map

package/dist/core/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/config/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6DAA2C"}

package/dist/core/constants.d.ts

@@ -50,6 +50,40 @@ export declare const AUTOWIRED_METADATA: unique symbol;
  * Key for storing @Provider() metadata
  */
 export declare const PROVIDER_METADATA: unique symbol;
+/**
+ * Key for storing @ProviderConfig() metadata on config provider classes.
+ *
+ * This metadata stores the injection token that identifies the config provider,
+ * allowing the auto-discovery mechanism to register it with the DI container.
+ *
+ * @example
+ * ```typescript
+ * @ProviderConfig('APP_CONFIG')
+ * class AppConfigProvider extends AbstractConfigProvider {
+ *   // Token 'APP_CONFIG' is stored in metadata
+ * }
+ * ```
+ */
+export declare const CONFIG_PROVIDER_METADATA: unique symbol;
+/**
+ * Key for storing @ConfigProperty() metadata on config class properties.
+ *
+ * This metadata maps class properties to environment variable names,
+ * supporting both explicit mapping and automatic upper_snake_case conversion.
+ * Stored as an array of `{ propertyKey: string, envKey: string }` objects.
+ *
+ * @example
+ * ```typescript
+ * class DatabaseConfig {
+ *   @ConfigProperty('DB_HOST')  // explicit mapping
+ *   host: string;
+ *
+ *   @ConfigProperty()  // auto-mapped to 'DB_PORT'
+ *   dbPort: number;
+ * }
+ * ```
+ */
+export declare const CONFIG_PROPERTY_METADATA: unique symbol;
 /**
  * Parameter types for injection
  */

package/dist/core/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;GAEG;AACH,oBAAY,SAAS;IACnB,IAAI,SAAS;IACb,KAAK,UAAU;IACf,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,cAAc,eAA2B,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,kBAAkB,eAA+B,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAM7D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;GAEG;AACH,oBAAY,SAAS;IACnB,IAAI,SAAS;IACb,KAAK,UAAU;IACf,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC"}

package/dist/core/constants.js

@@ -3,7 +3,7 @@
 // Metadata Keys for Reflect API
 // ============================================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CONFIG = exports.ParamType = exports.PROVIDER_METADATA = exports.AUTOWIRED_METADATA = exports.ZOD_SCHEMA_METADATA = exports.INJECT_METADATA = exports.HEADERS_METADATA = exports.HTTP_CODE_METADATA = exports.MIDDLEWARE_METADATA = exports.INTERCEPTORS_METADATA = exports.GUARDS_METADATA = exports.PARAM_METADATA = exports.INJECTABLE_METADATA = exports.ROUTES_METADATA = exports.CONTROLLER_METADATA = void 0;
+exports.DEFAULT_CONFIG = exports.ParamType = exports.CONFIG_PROPERTY_METADATA = exports.CONFIG_PROVIDER_METADATA = exports.PROVIDER_METADATA = exports.AUTOWIRED_METADATA = exports.ZOD_SCHEMA_METADATA = exports.INJECT_METADATA = exports.HEADERS_METADATA = exports.HTTP_CODE_METADATA = exports.MIDDLEWARE_METADATA = exports.INTERCEPTORS_METADATA = exports.GUARDS_METADATA = exports.PARAM_METADATA = exports.INJECTABLE_METADATA = exports.ROUTES_METADATA = exports.CONTROLLER_METADATA = void 0;
 /**
  * Key for storing controller metadata (prefix, routes)
  */
@@ -56,6 +56,43 @@ exports.AUTOWIRED_METADATA = Symbol('autowired:metadata');
  * Key for storing @Provider() metadata
  */
 exports.PROVIDER_METADATA = Symbol('provider:metadata');
+// ============================================================================
+// Configuration Metadata Keys
+// ============================================================================
+/**
+ * Key for storing @ProviderConfig() metadata on config provider classes.
+ *
+ * This metadata stores the injection token that identifies the config provider,
+ * allowing the auto-discovery mechanism to register it with the DI container.
+ *
+ * @example
+ * ```typescript
+ * @ProviderConfig('APP_CONFIG')
+ * class AppConfigProvider extends AbstractConfigProvider {
+ *   // Token 'APP_CONFIG' is stored in metadata
+ * }
+ * ```
+ */
+exports.CONFIG_PROVIDER_METADATA = Symbol('config:provider:metadata');
+/**
+ * Key for storing @ConfigProperty() metadata on config class properties.
+ *
+ * This metadata maps class properties to environment variable names,
+ * supporting both explicit mapping and automatic upper_snake_case conversion.
+ * Stored as an array of `{ propertyKey: string, envKey: string }` objects.
+ *
+ * @example
+ * ```typescript
+ * class DatabaseConfig {
+ *   @ConfigProperty('DB_HOST')  // explicit mapping
+ *   host: string;
+ *
+ *   @ConfigProperty()  // auto-mapped to 'DB_PORT'
+ *   dbPort: number;
+ * }
+ * ```
+ */
+exports.CONFIG_PROPERTY_METADATA = Symbol('config:property:metadata');
 /**
  * Parameter types for injection
  */

package/dist/core/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":";AAAA,+EAA+E;AAC/E,gCAAgC;AAChC,+EAA+E;;;AAE/E;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEvD;;GAEG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD;;GAEG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAErE;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAE/D;;GAEG;AACU,QAAA,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAE3D;;GAEG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAE/D;;GAEG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAE7D;;GAEG;AACH,IAAY,SAQX;AARD,WAAY,SAAS;IACnB,0BAAa,CAAA;IACb,4BAAe,CAAA;IACf,4BAAe,CAAA;IACf,gCAAmB,CAAA;IACnB,gCAAmB,CAAA;IACnB,4BAAe,CAAA;IACf,gCAAmB,CAAA;AACrB,CAAC,EARW,SAAS,yBAAT,SAAS,QAQpB;AAED;;GAEG;AACU,QAAA,cAAc,GAAG;IAC5B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,IAAI;IACZ,MAAM,EAAE,EAAE;CACF,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":";AAAA,+EAA+E;AAC/E,gCAAgC;AAChC,+EAA+E;;;AAE/E;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEvD;;GAEG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD;;GAEG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAErE;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAE/D;;GAEG;AACU,QAAA,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAE3D;;GAEG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD;;GAEG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;GAEG;AACU,QAAA,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAE/D;;GAEG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAE7D,+EAA+E;AAC/E,8BAA8B;AAC9B,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;GAiBG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAE3E;;GAEG;AACH,IAAY,SAQX;AARD,WAAY,SAAS;IACnB,0BAAa,CAAA;IACb,4BAAe,CAAA;IACf,4BAAe,CAAA;IACf,gCAAmB,CAAA;IACnB,gCAAmB,CAAA;IACnB,4BAAe,CAAA;IACf,gCAAmB,CAAA;AACrB,CAAC,EARW,SAAS,yBAAT,SAAS,QAQpB;AAED;;GAEG;AACU,QAAA,cAAc,GAAG;IAC5B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,IAAI;IACZ,MAAM,EAAE,EAAE;CACF,CAAC"}

package/dist/core/decorators/config-property.decorator.d.ts

@@ -0,0 +1,129 @@
+import 'reflect-metadata';
+/**
+ * Metadata for a single config property mapping
+ */
+export interface ConfigPropertyMapping {
+    /**
+     * The property name on the class
+     */
+    propertyKey: string;
+    /**
+     * The environment variable name to map from
+     */
+    envKey: string;
+}
+/**
+ * @ConfigProperty() decorator
+ *
+ * Maps a class property to an environment variable. If no explicit env key is provided,
+ * automatically converts the property name from camelCase to UPPER_SNAKE_CASE.
+ *
+ * This decorator stores metadata that will be read by AbstractConfigProvider
+ * during the populate() phase to assign validated environment values to properties.
+ *
+ * @param envKey - Optional explicit environment variable name (must be UPPERCASE)
+ *
+ * @example Auto-mapping (property name → UPPER_SNAKE_CASE):
+ * ```typescript
+ * import { ConfigProperty, ProviderConfig, AbstractConfigProvider } from '@riktajs/core';
+ * import { z } from 'zod';
+ *
+ * @ProviderConfig()
+ * export class DatabaseConfigProvider extends AbstractConfigProvider {
+ *   schema() {
+ *     return z.object({
+ *       DB_HOST: z.string(),
+ *       DB_PORT: z.coerce.number().int(),
+ *       DB_NAME: z.string(),
+ *     });
+ *   }
+ *
+ *   @ConfigProperty()  // Maps to 'DB_HOST'
+ *   dbHost!: string;
+ *
+ *   @ConfigProperty()  // Maps to 'DB_PORT'
+ *   dbPort!: number;
+ *
+ *   @ConfigProperty()  // Maps to 'DB_NAME'
+ *   dbName!: string;
+ * }
+ * ```
+ *
+ * @example Custom env key mapping:
+ * ```typescript
+ * @ProviderConfig()
+ * export class AppConfigProvider extends AbstractConfigProvider {
+ *   schema() {
+ *     return z.object({
+ *       PORT: z.coerce.number().int(),
+ *       NODE_ENV: z.enum(['development', 'production', 'test']),
+ *       API_SECRET_KEY: z.string(),
+ *     });
+ *   }
+ *
+ *   @ConfigProperty('PORT')
+ *   serverPort!: number;
+ *
+ *   @ConfigProperty('NODE_ENV')
+ *   environment!: 'development' | 'production' | 'test';
+ *
+ *   @ConfigProperty('API_SECRET_KEY')
+ *   secret!: string;
+ * }
+ * ```
+ *
+ * @example Mixed auto and custom mapping:
+ * ```typescript
+ * @ProviderConfig()
+ * export class ApiConfigProvider extends AbstractConfigProvider {
+ *   schema() {
+ *     return z.object({
+ *       API_KEY: z.string(),
+ *       API_URL: z.string().url(),
+ *       TIMEOUT: z.coerce.number().int(),
+ *     });
+ *   }
+ *
+ *   @ConfigProperty()  // Auto: apiKey → API_KEY
+ *   apiKey!: string;
+ *
+ *   @ConfigProperty()  // Auto: apiUrl → API_URL
+ *   apiUrl!: string;
+ *
+ *   @ConfigProperty('TIMEOUT')  // Custom mapping
+ *   requestTimeout!: number;
+ * }
+ * ```
+ */
+export declare function ConfigProperty(envKey?: string): PropertyDecorator;
+/**
+ * Helper to retrieve all config property mappings from a class
+ *
+ * @param target - The class constructor to retrieve mappings from
+ * @returns Array of property mappings, or empty array if none defined
+ *
+ * @example
+ * ```typescript
+ * const mappings = getConfigPropertyMappings(AppConfigProvider);
+ * console.log(mappings);
+ * // [
+ * //   { propertyKey: 'dbHost', envKey: 'DB_HOST' },
+ * //   { propertyKey: 'dbPort', envKey: 'DB_PORT' }
+ * // ]
+ * ```
+ */
+export declare function getConfigPropertyMappings(target: Function): ConfigPropertyMapping[];
+/**
+ * Check if a class has any @ConfigProperty decorated properties
+ *
+ * @param target - The class constructor to check
+ * @returns True if the class has at least one @ConfigProperty
+ */
+export declare function hasConfigProperties(target: Function): boolean;
+/**
+ * Clear the property name conversion cache
+ *
+ * @internal Used for testing
+ */
+export declare function clearPropertyNameCache(): void;
+//# sourceMappingURL=config-property.decorator.d.ts.map

package/dist/core/decorators/config-property.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-property.decorator.d.ts","sourceRoot":"","sources":["../../../src/core/decorators/config-property.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CA8DjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,QAAQ,GAAG,qBAAqB,EAAE,CAEnF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAG7D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}