@riktajs/core 0.7.0 → 0.9.0

package/README.md

@@ -49,6 +49,84 @@ await app.listen();
 - 📦 Built-in Dependency Injection
 - ✅ Zod Validation Integration
 
+## Provider Scopes
+
+Rikta supports three provider scopes:
+
+```typescript
+// Singleton (default) - shared instance
+@Injectable()
+class ConfigService {}
+
+// Transient - new instance each time
+@Injectable({ scope: 'transient' })
+class RequestLogger {}
+
+// Request - one instance per HTTP request
+@Injectable({ scope: 'request' })
+class RequestContext {}
+```
+
+## Strict Discovery Mode
+
+Enable strict discovery to catch import errors early:
+
+```typescript
+const app = await Rikta.create({
+  strictDiscovery: process.env.NODE_ENV !== 'production',
+  onDiscoveryError: (file, error) => {
+    console.warn(`Failed to import: ${file}`);
+  },
+});
+```
+
+## EventBus
+
+The EventBus provides pub/sub for lifecycle events:
+
+```typescript
+import { Injectable, Autowired, EventBus } from '@riktajs/core';
+
+@Injectable()
+class MonitorService {
+  @Autowired()
+  private events!: EventBus;
+
+  onProviderInit() {
+    this.events.on('app:listen', ({ address }) => {
+      console.log(`Server at ${address}`);
+    });
+  }
+}
+```
+
+## Interceptors
+
+Interceptors allow you to bind extra logic before/after method execution:
+
+```typescript
+import { Injectable, Interceptor, ExecutionContext, CallHandler, UseInterceptors } from '@riktajs/core';
+
+@Injectable()
+class LoggingInterceptor implements Interceptor {
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<unknown> {
+    const start = Date.now();
+    const result = await next.handle();
+    console.log(`Request took ${Date.now() - start}ms`);
+    return result;
+  }
+}
+
+@Controller('/api')
+@UseInterceptors(LoggingInterceptor)
+class ApiController {
+  @Get('/data')
+  getData() {
+    return { data: 'example' };
+  }
+}
+```
+
 ## License
 
 MIT

package/dist/core/application.js

@@ -27,7 +27,12 @@ class RiktaFactory {
             const patterns = Array.isArray(config.autowired) && config.autowired.length > 0
                 ? config.autowired
                 : ['./**'];
-            discoveredFiles = await (0, discovery_1.discoverModules)(patterns, callerDir);
+            discoveredFiles = await (0, discovery_1.discoverModules)({
+                patterns,
+                cwd: callerDir,
+                strict: config.strictDiscovery ?? false,
+                onImportError: config.onDiscoveryError,
+            });
         }
         const app = new RiktaApplicationImpl(config);
         await app.init(discoveredFiles);
@@ -169,7 +174,7 @@ class RiktaApplicationImpl {
         for (const { event, methodName } of metadata) {
             const method = instance[methodName];
             if (typeof method === 'function') {
-                this.events.on(event, method.bind(instance));
+                this.events.on(event, method.bind(instance), target.name);
             }
         }
     }
@@ -214,19 +219,21 @@ class RiktaApplicationImpl {
     async close(signal) {
         await this.events.emit('app:shutdown', { signal });
         const reversed = [...this.initializedProviders].reverse();
-        for (const { instance } of reversed) {
+        for (const { instance, name } of reversed) {
             if (this.hasHook(instance, 'onApplicationShutdown')) {
                 await instance.onApplicationShutdown(signal);
             }
             if (this.hasHook(instance, 'onProviderDestroy')) {
                 await instance.onProviderDestroy();
             }
+            this.events.removeByOwner(name);
         }
         await this.server.close();
         this.isListening = false;
         await this.events.emit('app:destroy', {
             uptime: Date.now() - this.startTime
         });
+        this.events.clear();
         if (!this.config.silent)
             console.log('\n👋 Application closed\n');
     }
@@ -239,4 +246,10 @@ class RiktaApplicationImpl {
     getContainer() {
         return this.container;
     }
+    getRouter() {
+        return this.router;
+    }
+    clearRouterCaches() {
+        this.router.clearAllCaches();
+    }
 }

package/dist/core/container/abstract-class.utils.d.ts

@@ -0,0 +1,10 @@
+import { Constructor } from '../types';
+export declare const IMPLEMENTS_METADATA: unique symbol;
+export declare const PRIMARY_METADATA: unique symbol;
+export declare function isAbstractClass(target: unknown): target is Constructor;
+export declare function extendsFrom(derived: Constructor, base: Constructor): boolean;
+export declare function getImplementedAbstract(target: Constructor): Constructor | undefined;
+export declare function isPrimaryImplementation(target: Constructor): boolean;
+export declare function setImplementsMetadata(target: Constructor, abstractClass: Constructor): void;
+export declare function setPrimaryMetadata(target: Constructor): void;
+export declare function markAsAbstract(target: Constructor): void;

package/dist/core/container/abstract-class.utils.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIMARY_METADATA = exports.IMPLEMENTS_METADATA = void 0;
+exports.isAbstractClass = isAbstractClass;
+exports.extendsFrom = extendsFrom;
+exports.getImplementedAbstract = getImplementedAbstract;
+exports.isPrimaryImplementation = isPrimaryImplementation;
+exports.setImplementsMetadata = setImplementsMetadata;
+exports.setPrimaryMetadata = setPrimaryMetadata;
+exports.markAsAbstract = markAsAbstract;
+exports.IMPLEMENTS_METADATA = Symbol('rikta:implements');
+exports.PRIMARY_METADATA = Symbol('rikta:primary');
+function isAbstractClass(target) {
+    if (typeof target !== 'function') {
+        return false;
+    }
+    const isMarkedAbstract = Reflect.getMetadata(exports.IMPLEMENTS_METADATA, target) === undefined
+        && Reflect.hasMetadata('abstract:class', target);
+    if (isMarkedAbstract) {
+        return true;
+    }
+    return Reflect.getMetadata('abstract:class', target) === true;
+}
+function extendsFrom(derived, base) {
+    if (!derived || !base) {
+        return false;
+    }
+    if (derived === base) {
+        return false;
+    }
+    let current = Object.getPrototypeOf(derived);
+    while (current && current !== Function.prototype) {
+        if (current === base) {
+            return true;
+        }
+        current = Object.getPrototypeOf(current);
+    }
+    return false;
+}
+function getImplementedAbstract(target) {
+    return Reflect.getMetadata(exports.IMPLEMENTS_METADATA, target);
+}
+function isPrimaryImplementation(target) {
+    return Reflect.getMetadata(exports.PRIMARY_METADATA, target) === true;
+}
+function setImplementsMetadata(target, abstractClass) {
+    Reflect.defineMetadata(exports.IMPLEMENTS_METADATA, abstractClass, target);
+}
+function setPrimaryMetadata(target) {
+    Reflect.defineMetadata(exports.PRIMARY_METADATA, true, target);
+}
+function markAsAbstract(target) {
+    Reflect.defineMetadata('abstract:class', true, target);
+}

package/dist/core/container/container.d.ts

@@ -17,9 +17,12 @@ export declare class Container {
     resolve<T>(token: Token<T>): T;
     resolveOptional<T>(token: Token<T>): T | undefined;
     private resolveToken;
+    private resolveAbstractClass;
     private resolveProvider;
     private resolveClass;
     private injectProperties;
+    private resolveWithName;
+    private resolveWithNameOptional;
     registerInstance<T>(target: Constructor<T>, instance: T): void;
     getProviders(): Token[];
     clearSingletons(): void;

package/dist/core/container/container.js

@@ -4,6 +4,9 @@ exports.container = exports.Container = void 0;
 require("reflect-metadata");
 const constants_1 = require("../constants");
 const injection_token_1 = require("./injection-token");
+const registry_1 = require("../registry");
+const abstract_class_utils_1 = require("./abstract-class.utils");
+const request_scope_1 = require("./request-scope");
 class Container {
     static instance;
     singletons = new Map();
@@ -70,12 +73,20 @@ class Container {
         }
         const config = this.providers.get(token);
         if (!config) {
+            if (typeof token === 'function') {
+                const implementation = this.resolveAbstractClass(token);
+                if (implementation) {
+                    const instance = this.resolveClass(implementation);
+                    this.singletons.set(token, instance);
+                    return instance;
+                }
+                if (!(0, abstract_class_utils_1.isAbstractClass)(token)) {
+                    return this.resolveClass(token);
+                }
+            }
             if (optional) {
                 return undefined;
             }
-            if (typeof token === 'function') {
-                return this.resolveClass(token);
-            }
             throw new Error(`No provider found for token: ${this.getTokenName(token)}`);
         }
         if (config.provider && typeof config.provider !== 'function') {
@@ -86,6 +97,34 @@ class Container {
         }
         throw new Error(`Cannot resolve token: ${this.getTokenName(token)}`);
     }
+    resolveAbstractClass(abstractClass, name) {
+        const config = this.providers.get(abstractClass);
+        if (config?.provider && 'useClass' in config.provider) {
+            return config.provider.useClass;
+        }
+        const implementations = registry_1.registry.getImplementations(abstractClass);
+        if (!implementations || implementations.length === 0) {
+            return undefined;
+        }
+        if (name) {
+            const named = implementations.find(i => i.name === name);
+            if (named) {
+                return named.implementation;
+            }
+            throw new Error(`No implementation named '${name}' found for abstract class ${abstractClass.name}. ` +
+                `Available names: ${implementations.filter(i => i.name).map(i => i.name).join(', ') || 'none'}`);
+        }
+        if (implementations.length === 1) {
+            return implementations[0].implementation;
+        }
+        const primary = implementations.find(i => i.isPrimary);
+        if (primary) {
+            return primary.implementation;
+        }
+        const implNames = implementations.map(i => i.implementation.name).join(', ');
+        throw new Error(`Multiple implementations found for abstract class ${abstractClass.name}: ${implNames}. ` +
+            `Use @Primary() to mark one as the default, or @Named() for qualified injection.`);
+    }
     resolveProvider(provider, scope) {
         if (typeof provider === 'function') {
             return this.resolveClass(provider);
@@ -128,6 +167,16 @@ class Container {
         if (scope === 'singleton' && this.singletons.has(target)) {
             return this.singletons.get(target);
         }
+        if (scope === 'request') {
+            if (!request_scope_1.requestScopeStorage.isInRequestScope()) {
+                throw new Error(`Cannot resolve request-scoped provider '${target.name}' outside of a request context. ` +
+                    `Request-scoped providers can only be resolved during HTTP request handling.`);
+            }
+            const existingInstance = request_scope_1.requestScopeStorage.get(target);
+            if (existingInstance !== undefined) {
+                return existingInstance;
+            }
+        }
         this.resolutionStack.add(target);
         try {
             const injectMeta = Reflect.getMetadata(constants_1.INJECT_METADATA, target) ?? [];
@@ -142,6 +191,7 @@ class Container {
                 const injectOverride = injectMeta.find(m => m.index === index);
                 const token = injectOverride?.token ?? paramType;
                 const isOptional = injectOverride?.optional ?? false;
+                const name = injectOverride?.name;
                 if (!token) {
                     if (isOptional) {
                         dependencies.push(undefined);
@@ -159,14 +209,17 @@ class Container {
                         `Use @Autowired(token) decorator.`);
                 }
                 dependencies.push(isOptional
-                    ? this.resolveOptional(token)
-                    : this.resolve(token));
+                    ? this.resolveWithNameOptional(token, name)
+                    : this.resolveWithName(token, name));
             }
             const instance = new target(...dependencies);
             this.injectProperties(target, instance);
             if (scope === 'singleton') {
                 this.singletons.set(target, instance);
             }
+            else if (scope === 'request') {
+                request_scope_1.requestScopeStorage.set(target, instance);
+            }
             return instance;
         }
         finally {
@@ -181,8 +234,8 @@ class Container {
             const isOptional = meta.optional ?? false;
             try {
                 const value = isOptional
-                    ? this.resolveOptional(meta.token)
-                    : this.resolve(meta.token);
+                    ? this.resolveWithNameOptional(meta.token, meta.name)
+                    : this.resolveWithName(meta.token, meta.name);
                 instance[meta.propertyKey] = value;
             }
             catch (error) {
@@ -192,6 +245,24 @@ class Container {
             }
         }
     }
+    resolveWithName(token, name) {
+        if (name && typeof token === 'function') {
+            const implementation = this.resolveAbstractClass(token, name);
+            if (implementation) {
+                return this.resolveClass(implementation);
+            }
+            throw new Error(`No implementation named '${name}' found for ${this.getTokenName(token)}`);
+        }
+        return this.resolve(token);
+    }
+    resolveWithNameOptional(token, name) {
+        try {
+            return this.resolveWithName(token, name);
+        }
+        catch {
+            return undefined;
+        }
+    }
     registerInstance(target, instance) {
         this.providers.set(target, { scope: 'singleton' });
         this.singletons.set(target, instance);

package/dist/core/container/implements.decorator.d.ts

@@ -0,0 +1,6 @@
+import 'reflect-metadata';
+import { AnyConstructor } from '../types';
+export declare function Implements<T extends AnyConstructor>(abstractClass: T): ClassDecorator;
+export declare function Primary(): ClassDecorator;
+export declare function Named(name: string): ClassDecorator;
+export declare function AbstractClass(): ClassDecorator;

package/dist/core/container/implements.decorator.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Implements = Implements;
+exports.Primary = Primary;
+exports.Named = Named;
+exports.AbstractClass = AbstractClass;
+require("reflect-metadata");
+const abstract_class_utils_1 = require("./abstract-class.utils");
+const registry_1 = require("../registry");
+function Implements(abstractClass) {
+    return (target) => {
+        (0, abstract_class_utils_1.setImplementsMetadata)(target, abstractClass);
+        (0, abstract_class_utils_1.markAsAbstract)(abstractClass);
+        const name = Reflect.getMetadata('rikta:named', target);
+        registry_1.registry.registerAbstractImplementation(abstractClass, target, name);
+        const isPrimary = Reflect.getMetadata('rikta:is-primary', target) === true;
+        if (isPrimary) {
+            registry_1.registry.setPrimaryImplementation(abstractClass, target);
+        }
+    };
+}
+function Primary() {
+    return (target) => {
+        (0, abstract_class_utils_1.setPrimaryMetadata)(target);
+        const abstractClass = Reflect.getMetadata(abstract_class_utils_1.IMPLEMENTS_METADATA, target);
+        if (abstractClass) {
+            registry_1.registry.setPrimaryImplementation(abstractClass, target);
+        }
+        Reflect.defineMetadata('rikta:is-primary', true, target);
+    };
+}
+function Named(name) {
+    return (target) => {
+        Reflect.defineMetadata('rikta:named', name, target);
+        const abstractClass = Reflect.getMetadata(abstract_class_utils_1.IMPLEMENTS_METADATA, target);
+        if (abstractClass) {
+            registry_1.registry.setImplementationName(abstractClass, target, name);
+        }
+    };
+}
+function AbstractClass() {
+    return (target) => {
+        (0, abstract_class_utils_1.markAsAbstract)(target);
+    };
+}

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

@@ -1,2 +1,5 @@
 export * from './container';
 export * from './injection-token';
+export * from './abstract-class.utils';
+export * from './implements.decorator';
+export * from './request-scope';

package/dist/core/container/index.js

@@ -16,3 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./container"), exports);
 __exportStar(require("./injection-token"), exports);
+__exportStar(require("./abstract-class.utils"), exports);
+__exportStar(require("./implements.decorator"), exports);
+__exportStar(require("./request-scope"), exports);

package/dist/core/container/request-scope.d.ts

@@ -0,0 +1,16 @@
+import { Token } from './injection-token';
+export declare class RequestScopeStorage {
+    private static instance;
+    private readonly asyncLocalStorage;
+    private constructor();
+    static getInstance(): RequestScopeStorage;
+    static reset(): void;
+    run<T>(fn: () => T): T;
+    runAsync<T>(fn: () => Promise<T>): Promise<T>;
+    isInRequestScope(): boolean;
+    get<T>(token: Token<T>): T | undefined;
+    set<T>(token: Token<T>, instance: T): void;
+    has(token: Token): boolean;
+    getStore(): Map<Token, unknown> | undefined;
+}
+export declare const requestScopeStorage: RequestScopeStorage;

package/dist/core/container/request-scope.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestScopeStorage = exports.RequestScopeStorage = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+class RequestScopeStorage {
+    static instance;
+    asyncLocalStorage = new node_async_hooks_1.AsyncLocalStorage();
+    constructor() { }
+    static getInstance() {
+        if (!RequestScopeStorage.instance) {
+            RequestScopeStorage.instance = new RequestScopeStorage();
+        }
+        return RequestScopeStorage.instance;
+    }
+    static reset() {
+        RequestScopeStorage.instance = new RequestScopeStorage();
+    }
+    run(fn) {
+        const store = new Map();
+        return this.asyncLocalStorage.run(store, fn);
+    }
+    async runAsync(fn) {
+        const store = new Map();
+        return this.asyncLocalStorage.run(store, fn);
+    }
+    isInRequestScope() {
+        return this.asyncLocalStorage.getStore() !== undefined;
+    }
+    get(token) {
+        const store = this.asyncLocalStorage.getStore();
+        if (!store) {
+            return undefined;
+        }
+        return store.get(token);
+    }
+    set(token, instance) {
+        const store = this.asyncLocalStorage.getStore();
+        if (!store) {
+            throw new Error('Cannot set request-scoped instance outside of a request context. ' +
+                'Make sure RequestScopeStorage.run() or runAsync() is being used.');
+        }
+        store.set(token, instance);
+    }
+    has(token) {
+        const store = this.asyncLocalStorage.getStore();
+        return store?.has(token) ?? false;
+    }
+    getStore() {
+        return this.asyncLocalStorage.getStore();
+    }
+}
+exports.RequestScopeStorage = RequestScopeStorage;
+exports.requestScopeStorage = RequestScopeStorage.getInstance();

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

@@ -5,6 +5,7 @@ export interface AutowiredMetadata {
     index?: number;
     propertyKey?: string;
     optional?: boolean;
+    name?: string;
 }
-export declare function Autowired(token?: Token): ParameterDecorator & PropertyDecorator;
+export declare function Autowired(token?: Token, name?: string): ParameterDecorator & PropertyDecorator;
 export declare function Optional(): ParameterDecorator & PropertyDecorator;

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

@@ -4,7 +4,7 @@ exports.Autowired = Autowired;
 exports.Optional = Optional;
 require("reflect-metadata");
 const constants_1 = require("../constants");
-function Autowired(token) {
+function Autowired(token, name) {
     return (target, propertyKey, parameterIndex) => {
         if (typeof parameterIndex === 'number') {
             const paramTypes = Reflect.getMetadata('design:paramtypes', target) ?? [];
@@ -18,6 +18,7 @@ function Autowired(token) {
             existingInjects.push({
                 token: resolvedToken,
                 index: parameterIndex,
+                name,
             });
             Reflect.defineMetadata(constants_1.INJECT_METADATA, existingInjects, target);
         }
@@ -32,6 +33,7 @@ function Autowired(token) {
             existingAutowires.push({
                 token: resolvedToken,
                 propertyKey: String(propertyKey),
+                name,
             });
             Reflect.defineMetadata(constants_1.AUTOWIRED_METADATA, existingAutowires, target.constructor);
         }

package/dist/core/discovery.d.ts

@@ -1,2 +1,3 @@
-export declare function discoverModules(patterns?: string[], cwd?: string): Promise<string[]>;
+import { DiscoveryOptions } from './exceptions/discovery.exception';
+export declare function discoverModules(optionsOrPatterns?: DiscoveryOptions | string[], cwd?: string): Promise<string[]>;
 export declare function getCallerDirectory(): string;

package/dist/core/discovery.js

@@ -41,6 +41,7 @@ exports.getCallerDirectory = getCallerDirectory;
 const fast_glob_1 = __importDefault(require("fast-glob"));
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
+const discovery_exception_1 = require("./exceptions/discovery.exception");
 const DEFAULT_IGNORE_PATTERNS = [
     '**/node_modules/**',
     '**/dist/**',
@@ -79,8 +80,14 @@ async function containsRiktaDecorators(filePath) {
         return false;
     }
 }
-async function discoverModules(patterns = ['./**/*.{ts,js}'], cwd) {
-    const baseDir = cwd ?? getEntryPointDirectory();
+async function discoverModules(optionsOrPatterns = ['./**/*.{ts,js}'], cwd) {
+    const options = Array.isArray(optionsOrPatterns)
+        ? { patterns: optionsOrPatterns, cwd }
+        : optionsOrPatterns;
+    const patterns = options.patterns ?? ['./**/*.{ts,js}'];
+    const strict = options.strict ?? false;
+    const onImportError = options.onImportError;
+    const baseDir = options.cwd ?? cwd ?? getEntryPointDirectory();
     const absoluteBaseDir = path_1.default.isAbsolute(baseDir)
         ? baseDir
         : path_1.default.resolve(process.cwd(), baseDir);
@@ -105,25 +112,30 @@ async function discoverModules(patterns = ['./**/*.{ts,js}'], cwd) {
         ignore: DEFAULT_IGNORE_PATTERNS,
         onlyFiles: true,
     });
-    const riktaFiles = [];
-    for (const file of files) {
-        if (await containsRiktaDecorators(file)) {
-            riktaFiles.push(file);
-        }
-    }
+    const decoratorChecks = await Promise.all(files.map(async (file) => ({ file, hasDecorators: await containsRiktaDecorators(file) })));
+    const riktaFiles = decoratorChecks
+        .filter(({ hasDecorators }) => hasDecorators)
+        .map(({ file }) => file);
     const importedFiles = [];
+    const failedImports = [];
     for (const file of riktaFiles) {
         try {
             const importPath = file.replace(/\.ts$/, '');
             await Promise.resolve(`${importPath}`).then(s => __importStar(require(s)));
             importedFiles.push(file);
         }
-        catch (error) {
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            onImportError?.(file, error);
             if (process.env.DEBUG) {
-                console.warn(`[Rikta] Failed to import ${file}:`, error);
+                console.warn(`[Rikta] Failed to import ${file}:`, error.message);
             }
+            failedImports.push({ filePath: file, error });
         }
     }
+    if (strict && failedImports.length > 0) {
+        throw new discovery_exception_1.DiscoveryException(failedImports);
+    }
     return importedFiles;
 }
 function getCallerDirectory() {

package/dist/core/exceptions/discovery.exception.d.ts

@@ -0,0 +1,18 @@
+export declare class DiscoveryException extends Error {
+    readonly filePath: string;
+    readonly originalError: Error;
+    readonly failedImports: DiscoveryFailure[];
+    constructor(filePath: string, originalError: Error);
+    constructor(failures: DiscoveryFailure[]);
+    getReport(): string;
+}
+export interface DiscoveryFailure {
+    filePath: string;
+    error: Error;
+}
+export interface DiscoveryOptions {
+    patterns?: string[];
+    cwd?: string;
+    strict?: boolean;
+    onImportError?: (filePath: string, error: Error) => void;
+}