@riktajs/core 0.4.4 → 0.4.6

package/dist/core/container/injection-token.d.ts

@@ -1,24 +1,3 @@
-/**
- * Injection Token
- *
- * Used to identify dependencies that are not classes (interfaces, values, etc.)
- * Similar to NestJS InjectionToken and Angular's InjectionToken.
- *
- * @example
- * ```typescript
- * // Define a token for a configuration object
- * const CONFIG_TOKEN = new InjectionToken<AppConfig>('app.config');
- *
- * // Register with the container
- * container.registerValue(CONFIG_TOKEN, { apiUrl: 'https://api.example.com' });
- *
- * // Inject using the token
- * @Injectable()
- * class ApiService {
- *   constructor(@Autowired(CONFIG_TOKEN) private config: AppConfig) {}
- * }
- * ```
- */
 export declare class InjectionToken<T = unknown> {
     readonly description: string;
     readonly options?: {
@@ -29,14 +8,7 @@ export declare class InjectionToken<T = unknown> {
     } | undefined);
     toString(): string;
 }
-/**
- * Type for any valid injection token
- * Can be a class constructor, InjectionToken, string, or symbol
- */
 export type Token<T = unknown> = (new (...args: unknown[]) => T) | InjectionToken<T> | string | symbol;
-/**
- * Provider definition for custom providers
- */
 export interface ClassProvider<T = unknown> {
     provide: Token<T>;
     useClass: new (...args: unknown[]) => T;
@@ -55,4 +27,3 @@ export interface ExistingProvider<T = unknown> {
     useExisting: Token<T>;
 }
 export type ProviderDefinition<T = unknown> = ClassProvider<T> | ValueProvider<T> | FactoryProvider<T> | ExistingProvider<T> | (new (...args: unknown[]) => T);
-//# sourceMappingURL=injection-token.d.ts.map

package/dist/core/container/injection-token.js

@@ -1,27 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InjectionToken = void 0;
-/**
- * Injection Token
- *
- * Used to identify dependencies that are not classes (interfaces, values, etc.)
- * Similar to NestJS InjectionToken and Angular's InjectionToken.
- *
- * @example
- * ```typescript
- * // Define a token for a configuration object
- * const CONFIG_TOKEN = new InjectionToken<AppConfig>('app.config');
- *
- * // Register with the container
- * container.registerValue(CONFIG_TOKEN, { apiUrl: 'https://api.example.com' });
- *
- * // Inject using the token
- * @Injectable()
- * class ApiService {
- *   constructor(@Autowired(CONFIG_TOKEN) private config: AppConfig) {}
- * }
- * ```
- */
 class InjectionToken {
     description;
     options;
@@ -34,4 +13,3 @@ class InjectionToken {
     }
 }
 exports.InjectionToken = InjectionToken;
-//# sourceMappingURL=injection-token.js.map

package/dist/core/decorators/autowired.decorator.d.ts

@@ -1,72 +1,10 @@
 import 'reflect-metadata';
 import { Token } from '../container/injection-token';
-/**
- * Metadata for autowired parameters/properties
- */
 export interface AutowiredMetadata {
     token: Token;
     index?: number;
     propertyKey?: string;
     optional?: boolean;
 }
-/**
- * @Autowired() decorator
- *
- * Universal dependency injection decorator for both:
- * - Constructor parameters
- * - Class properties
- *
- * Automatically infers the type when no token is provided.
- *
- * @example Property injection (most common):
- * ```typescript
- * @Controller('/users')
- * export class UserController {
- *   @Autowired()
- *   private userService!: UserService;
- *
- *   @Autowired(LOGGER)  // With token for interfaces
- *   private logger!: Logger;
- * }
- * ```
- *
- * @example Constructor injection:
- * ```typescript
- * @Injectable()
- * class ApiService {
- *   constructor(
- *     @Autowired() private userService: UserService,
- *     @Autowired(CONFIG) private config: AppConfig
- *   ) {}
- * }
- * ```
- */
 export declare function Autowired(token?: Token): ParameterDecorator & PropertyDecorator;
-/**
- * @Optional() decorator
- *
- * Marks an injection as optional. If the dependency is not found,
- * undefined will be injected instead of throwing an error.
- *
- * @example Property injection:
- * ```typescript
- * @Controller()
- * export class AppController {
- *   @Optional()
- *   @Autowired()
- *   private analytics?: AnalyticsService;
- * }
- * ```
- *
- * @example Constructor injection:
- * ```typescript
- * @Injectable()
- * class NotificationService {
- *   constructor(
- *     @Optional() @Autowired(SLACK) private slack?: SlackClient
- *   ) {}
- * }
- * ```
- */
 export declare function Optional(): ParameterDecorator & PropertyDecorator;
-//# sourceMappingURL=autowired.decorator.d.ts.map

package/dist/core/decorators/autowired.decorator.js

@@ -4,42 +4,9 @@ exports.Autowired = Autowired;
 exports.Optional = Optional;
 require("reflect-metadata");
 const constants_1 = require("../constants");
-/**
- * @Autowired() decorator
- *
- * Universal dependency injection decorator for both:
- * - Constructor parameters
- * - Class properties
- *
- * Automatically infers the type when no token is provided.
- *
- * @example Property injection (most common):
- * ```typescript
- * @Controller('/users')
- * export class UserController {
- *   @Autowired()
- *   private userService!: UserService;
- *
- *   @Autowired(LOGGER)  // With token for interfaces
- *   private logger!: Logger;
- * }
- * ```
- *
- * @example Constructor injection:
- * ```typescript
- * @Injectable()
- * class ApiService {
- *   constructor(
- *     @Autowired() private userService: UserService,
- *     @Autowired(CONFIG) private config: AppConfig
- *   ) {}
- * }
- * ```
- */
 function Autowired(token) {
     return (target, propertyKey, parameterIndex) => {
         if (typeof parameterIndex === 'number') {
-            // Constructor parameter injection
             const paramTypes = Reflect.getMetadata('design:paramtypes', target) ?? [];
             const inferredType = paramTypes[parameterIndex];
             const resolvedToken = token ?? inferredType;
@@ -55,7 +22,6 @@ function Autowired(token) {
             Reflect.defineMetadata(constants_1.INJECT_METADATA, existingInjects, target);
         }
         else if (propertyKey !== undefined) {
-            // Property injection
             const inferredType = Reflect.getMetadata('design:type', target, propertyKey);
             const resolvedToken = token ?? inferredType;
             if (!resolvedToken) {
@@ -71,36 +37,9 @@ function Autowired(token) {
         }
     };
 }
-/**
- * @Optional() decorator
- *
- * Marks an injection as optional. If the dependency is not found,
- * undefined will be injected instead of throwing an error.
- *
- * @example Property injection:
- * ```typescript
- * @Controller()
- * export class AppController {
- *   @Optional()
- *   @Autowired()
- *   private analytics?: AnalyticsService;
- * }
- * ```
- *
- * @example Constructor injection:
- * ```typescript
- * @Injectable()
- * class NotificationService {
- *   constructor(
- *     @Optional() @Autowired(SLACK) private slack?: SlackClient
- *   ) {}
- * }
- * ```
- */
 function Optional() {
     return (target, propertyKey, parameterIndex) => {
         if (typeof parameterIndex === 'number') {
-            // Constructor parameter
             const existingInjects = Reflect.getMetadata(constants_1.INJECT_METADATA, target) ?? [];
             let meta = existingInjects.find(m => m.index === parameterIndex);
             if (meta) {
@@ -120,7 +59,6 @@ function Optional() {
             Reflect.defineMetadata(constants_1.INJECT_METADATA, existingInjects, target);
         }
         else if (propertyKey !== undefined) {
-            // Property injection
             const existingAutowires = Reflect.getMetadata(constants_1.AUTOWIRED_METADATA, target.constructor) ?? [];
             let meta = existingAutowires.find(m => m.propertyKey === String(propertyKey));
             if (meta) {
@@ -140,4 +78,3 @@ function Optional() {
         }
     };
 }
-//# sourceMappingURL=autowired.decorator.js.map

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

@@ -1,129 +1,9 @@
 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, Provider, AbstractConfigProvider } from '@riktajs/core';
- * import { z } from 'zod';
- *
- * @Provider()
- * 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
- * @Provider()
- * 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
- * @Provider()
- * 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.js

@@ -6,200 +6,60 @@ exports.hasConfigProperties = hasConfigProperties;
 exports.clearPropertyNameCache = clearPropertyNameCache;
 require("reflect-metadata");
 const constants_1 = require("../constants");
-/**
- * Cache for converted property names to avoid recomputation
- * Map<propertyKey, envKey>
- */
 const propertyNameCache = new Map();
-/**
- * Convert a camelCase property name to UPPER_SNAKE_CASE
- *
- * @param propertyName - The property name to convert
- * @returns The converted UPPER_SNAKE_CASE name
- *
- * @example
- * ```typescript
- * toUpperSnakeCase('dbHost')      // 'DB_HOST'
- * toUpperSnakeCase('apiKey')      // 'API_KEY'
- * toUpperSnakeCase('port')        // 'PORT'
- * toUpperSnakeCase('maxRetries')  // 'MAX_RETRIES'
- * ```
- */
 function toUpperSnakeCase(propertyName) {
-    // Check cache first (tip: cache derived names)
     if (propertyNameCache.has(propertyName)) {
         return propertyNameCache.get(propertyName);
     }
-    // Convert camelCase/PascalCase to UPPER_SNAKE_CASE
     const envKey = propertyName
         .replace(/([A-Z])/g, '_$1')
         .toUpperCase()
         .replace(/^_/, '');
-    // Cache for future use
     propertyNameCache.set(propertyName, envKey);
     return envKey;
 }
-/**
- * @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, Provider, AbstractConfigProvider } from '@riktajs/core';
- * import { z } from 'zod';
- *
- * @Provider()
- * 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
- * @Provider()
- * 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
- * @Provider()
- * 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;
- * }
- * ```
- */
 function ConfigProperty(envKey) {
     return (target, propertyKey) => {
         if (typeof propertyKey === 'symbol') {
             throw new Error(`@ConfigProperty: Symbol properties are not supported. ` +
                 `Property "${String(propertyKey)}" must be a string.`);
         }
-        // Determine the environment variable name
         const finalEnvKey = envKey ?? toUpperSnakeCase(propertyKey);
-        // Validate env key format
         if (!finalEnvKey || typeof finalEnvKey !== 'string') {
             throw new Error(`@ConfigProperty: Invalid env key for property "${propertyKey}". ` +
                 `Env key must be a non-empty string.`);
         }
-        // Ensure env key is uppercase (convention)
         if (finalEnvKey !== finalEnvKey.toUpperCase()) {
             throw new Error(`@ConfigProperty: Env key "${finalEnvKey}" for property "${propertyKey}" must be UPPERCASE. ` +
                 `Use "${finalEnvKey.toUpperCase()}" instead.`);
         }
-        // Get existing metadata or initialize
         const constructor = target.constructor;
         const existingMappings = Reflect.getMetadata(constants_1.CONFIG_PROPERTY_METADATA, constructor) || [];
-        // Check for duplicate property decorations
         const duplicate = existingMappings.find(m => m.propertyKey === propertyKey);
         if (duplicate) {
             throw new Error(`@ConfigProperty: Property "${propertyKey}" on class "${constructor.name}" ` +
                 `is already decorated. Remove the duplicate @ConfigProperty decorator.`);
         }
-        // Check for duplicate env key mappings
         const duplicateEnvKey = existingMappings.find(m => m.envKey === finalEnvKey);
         if (duplicateEnvKey) {
             throw new Error(`@ConfigProperty: Env key "${finalEnvKey}" is already mapped to property "${duplicateEnvKey.propertyKey}" ` +
                 `on class "${constructor.name}". Each env key can only be mapped to one property.`);
         }
-        // Add the new mapping
         const newMapping = {
             propertyKey,
             envKey: finalEnvKey,
         };
         const updatedMappings = [...existingMappings, newMapping];
-        // Store metadata
         Reflect.defineMetadata(constants_1.CONFIG_PROPERTY_METADATA, updatedMappings, constructor);
     };
 }
-/**
- * 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' }
- * // ]
- * ```
- */
 function getConfigPropertyMappings(target) {
     return Reflect.getMetadata(constants_1.CONFIG_PROPERTY_METADATA, target) || [];
 }
-/**
- * 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
- */
 function hasConfigProperties(target) {
     const mappings = getConfigPropertyMappings(target);
     return mappings.length > 0;
 }
-/**
- * Clear the property name conversion cache
- *
- * @internal Used for testing
- */
 function clearPropertyNameCache() {
     propertyNameCache.clear();
 }
-//# sourceMappingURL=config-property.decorator.js.map

package/dist/core/decorators/controller.decorator.d.ts

@@ -1,33 +1,5 @@
 import 'reflect-metadata';
-/**
- * Controller options
- */
 export interface ControllerOptions {
-    /** Route prefix for all routes in this controller */
     prefix?: string;
 }
-/**
- * @Controller() decorator
- *
- * Marks a class as a controller that handles HTTP requests.
- * Controllers are automatically:
- * - Registered in the global registry for auto-discovery
- * - Injectable and registered in the DI container
- *
- * @example
- * ```typescript
- * @Controller('/users')
- * class UserController {
- *   @Autowired()
- *   private userService!: UserService;
- *
- *   @Get('/')
- *   getUsers() { return []; }
- *
- *   @Get('/:id')
- *   getUser(@Param('id') id: string) { return { id }; }
- * }
- * ```
- */
 export declare function Controller(prefixOrOptions?: string | ControllerOptions): ClassDecorator;
-//# sourceMappingURL=controller.decorator.d.ts.map

package/dist/core/decorators/controller.decorator.js

@@ -5,46 +5,17 @@ require("reflect-metadata");
 const constants_1 = require("../constants");
 const container_1 = require("../container/container");
 const registry_1 = require("../registry");
-/**
- * @Controller() decorator
- *
- * Marks a class as a controller that handles HTTP requests.
- * Controllers are automatically:
- * - Registered in the global registry for auto-discovery
- * - Injectable and registered in the DI container
- *
- * @example
- * ```typescript
- * @Controller('/users')
- * class UserController {
- *   @Autowired()
- *   private userService!: UserService;
- *
- *   @Get('/')
- *   getUsers() { return []; }
- *
- *   @Get('/:id')
- *   getUser(@Param('id') id: string) { return { id }; }
- * }
- * ```
- */
 function Controller(prefixOrOptions) {
     return (target) => {
         const prefix = typeof prefixOrOptions === 'string'
             ? prefixOrOptions
             : prefixOrOptions?.prefix ?? '';
-        // Normalize prefix (ensure it starts with / if not empty)
         const normalizedPrefix = prefix
             ? (prefix.startsWith('/') ? prefix : `/${prefix}`)
             : '';
-        // Store controller metadata
         Reflect.defineMetadata(constants_1.CONTROLLER_METADATA, { prefix: normalizedPrefix }, target);
-        // Mark as injectable
         Reflect.defineMetadata(constants_1.INJECTABLE_METADATA, { scope: 'singleton' }, target);
-        // Register in DI container
         container_1.container.register(target, { scope: 'singleton' });
-        // Auto-register in global registry for discovery
         registry_1.registry.registerController(target);
     };
 }
-//# sourceMappingURL=controller.decorator.js.map

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

@@ -5,4 +5,3 @@ export * from './param.decorator';
 export * from './autowired.decorator';
 export * from './provider.decorator';
 export * from './config-property.decorator';
-//# sourceMappingURL=index.d.ts.map

package/dist/core/decorators/index.js

@@ -14,7 +14,6 @@ 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 });
-// Export all decorators
 __exportStar(require("./injectable.decorator"), exports);
 __exportStar(require("./controller.decorator"), exports);
 __exportStar(require("./route.decorator"), exports);
@@ -22,4 +21,3 @@ __exportStar(require("./param.decorator"), exports);
 __exportStar(require("./autowired.decorator"), exports);
 __exportStar(require("./provider.decorator"), exports);
 __exportStar(require("./config-property.decorator"), exports);
-//# sourceMappingURL=index.js.map