honest-node 1.0.0

package/dist/managers/parameter.resolver.d.ts

@@ -0,0 +1,13 @@
+import type { ParameterResolutionInput } from '../interfaces';
+import type { ILogger } from '../interfaces';
+import { ComponentManager } from './component.manager';
+/**
+ * Resolves route handler arguments from parameter decorator metadata.
+ */
+export declare class ParameterResolver {
+    private readonly componentManager;
+    private readonly logger;
+    private readonly debugPipeline;
+    constructor(componentManager: ComponentManager, logger?: ILogger, debugPipeline?: boolean);
+    resolveArguments(input: ParameterResolutionInput): Promise<unknown[]>;
+}

package/dist/managers/parameter.resolver.js

@@ -0,0 +1,58 @@
+import { NoopLogger } from '../loggers';
+import { ComponentManager } from './component.manager';
+/**
+ * Resolves route handler arguments from parameter decorator metadata.
+ */
+export class ParameterResolver {
+    componentManager;
+    logger;
+    debugPipeline;
+    constructor(componentManager, logger = new NoopLogger(), debugPipeline = false) {
+        this.componentManager = componentManager;
+        this.logger = logger;
+        this.debugPipeline = debugPipeline;
+    }
+    async resolveArguments(input) {
+        const { controllerName, handlerName, handlerArity, handlerParams, handlerPipes, context } = input;
+        const maxDecoratorIndex = handlerParams.length > 0 ? Math.max(...handlerParams.map((parameter) => parameter.index)) : -1;
+        const args = new Array(Math.max(handlerArity, maxDecoratorIndex + 1));
+        const decoratedIndices = new Set(handlerParams.map((parameter) => parameter.index));
+        if (this.debugPipeline && maxDecoratorIndex >= 0) {
+            const sparseIndices = [];
+            for (let i = 0; i <= maxDecoratorIndex; i++) {
+                if (!decoratedIndices.has(i)) {
+                    sparseIndices.push(i);
+                }
+            }
+            const hasOutOfRangeDecoratorIndex = maxDecoratorIndex >= handlerArity;
+            if (sparseIndices.length > 0 || hasOutOfRangeDecoratorIndex) {
+                this.logger.emit({
+                    level: 'warn',
+                    category: 'pipeline',
+                    message: `Potential parameter binding mismatch at ${controllerName}.${String(handlerName)}`,
+                    details: {
+                        handlerArity,
+                        maxDecoratorIndex,
+                        sparseIndices,
+                        handlerParamCount: handlerParams.length
+                    }
+                });
+            }
+        }
+        for (const parameter of handlerParams) {
+            if (typeof parameter.factory !== 'function') {
+                throw new Error(`Invalid parameter decorator metadata for ${controllerName}.${String(handlerName)}`);
+            }
+            const rawValue = await parameter.factory(parameter.data, context);
+            const transformedValue = await this.componentManager.executePipes(rawValue, {
+                type: parameter.name,
+                metatype: parameter.metatype,
+                data: typeof parameter.data === 'string' || typeof parameter.data === 'undefined'
+                    ? parameter.data
+                    : String(parameter.data)
+            }, handlerPipes);
+            args[parameter.index] = transformedValue;
+        }
+        return args;
+    }
+}

package/dist/managers/pipeline.executor.d.ts

@@ -0,0 +1,28 @@
+import type { Context } from 'hono';
+import type { ILogger, ParameterMetadata } from '../interfaces';
+import type { IPipe } from '../interfaces';
+import { ComponentManager } from './component.manager';
+import { HandlerInvoker } from './handler.invoker';
+import { ParameterResolver } from './parameter.resolver';
+import type { Constructor } from '../types';
+export interface PipelineExecutionInput {
+    controllerClass: Constructor;
+    handlerName: string | symbol;
+    handler: (...args: unknown[]) => Promise<unknown> | unknown;
+    handlerParams: ReadonlyArray<ParameterMetadata>;
+    handlerPipes: ReadonlyArray<IPipe>;
+    contextIndex?: number;
+    context: Context;
+}
+/**
+ * Executes guard, parameter-resolution, and handler invocation stages.
+ */
+export declare class PipelineExecutor {
+    private readonly componentManager;
+    private readonly parameterResolver;
+    private readonly handlerInvoker;
+    private readonly logger;
+    private readonly debugPipeline;
+    constructor(componentManager: ComponentManager, parameterResolver: ParameterResolver, handlerInvoker: HandlerInvoker, logger?: ILogger, debugPipeline?: boolean);
+    execute(input: PipelineExecutionInput): Promise<unknown>;
+}

package/dist/managers/pipeline.executor.js

@@ -0,0 +1,71 @@
+import { HTTPException } from 'hono/http-exception';
+import { HONEST_PIPELINE_CONTROLLER_KEY, HONEST_PIPELINE_HANDLER_KEY } from '../constants';
+import { NoopLogger } from '../loggers';
+import { ComponentManager } from './component.manager';
+import { HandlerInvoker } from './handler.invoker';
+import { ParameterResolver } from './parameter.resolver';
+/**
+ * Executes guard, parameter-resolution, and handler invocation stages.
+ */
+export class PipelineExecutor {
+    componentManager;
+    parameterResolver;
+    handlerInvoker;
+    logger;
+    debugPipeline;
+    constructor(componentManager, parameterResolver, handlerInvoker, logger = new NoopLogger(), debugPipeline = false) {
+        this.componentManager = componentManager;
+        this.parameterResolver = parameterResolver;
+        this.handlerInvoker = handlerInvoker;
+        this.logger = logger;
+        this.debugPipeline = debugPipeline;
+    }
+    async execute(input) {
+        const { controllerClass, handlerName, handler, handlerParams, handlerPipes, contextIndex, context } = input;
+        context.set(HONEST_PIPELINE_CONTROLLER_KEY, controllerClass);
+        context.set(HONEST_PIPELINE_HANDLER_KEY, String(handlerName));
+        const guards = this.componentManager.getHandlerGuards(controllerClass, handlerName);
+        for (const guard of guards) {
+            const canActivate = await guard.canActivate(context);
+            if (!canActivate) {
+                if (this.debugPipeline) {
+                    this.logger.emit({
+                        level: 'warn',
+                        category: 'pipeline',
+                        message: `Guard rejected request at ${controllerClass.name}.${String(handlerName)}`,
+                        details: { guard: guard.constructor?.name || 'UnknownGuard' }
+                    });
+                }
+                throw new HTTPException(403, {
+                    message: `Forbidden by ${guard.constructor?.name || 'UnknownGuard'} at ${controllerClass.name}.${String(handlerName)}`
+                });
+            }
+        }
+        const args = await this.parameterResolver.resolveArguments({
+            controllerName: controllerClass.name,
+            handlerName,
+            handlerArity: handler.length,
+            handlerParams,
+            handlerPipes,
+            context
+        });
+        if (this.debugPipeline) {
+            this.logger.emit({
+                level: 'debug',
+                category: 'pipeline',
+                message: `Resolved handler arguments for ${controllerClass.name}.${String(handlerName)}`,
+                details: {
+                    guardCount: guards.length,
+                    parameterCount: handlerParams.length,
+                    pipeCount: handlerPipes.length
+                }
+            });
+        }
+        return this.handlerInvoker.invoke({
+            handler,
+            args,
+            context,
+            contextIndex
+        });
+    }
+}

package/dist/managers/route.manager.d.ts

@@ -0,0 +1,36 @@
+import type { Hono } from 'hono';
+import { VERSION_NEUTRAL } from '../constants';
+import type { DiContainer, ILogger, IMetadataRepository } from '../interfaces';
+import { ComponentManager } from './component.manager';
+import { RouteRegistry } from '../registries/route.registry';
+import type { Constructor } from '../types';
+/**
+ * Manager class for handling route registration in the Honest framework.
+ *
+ * Receives all per-app dependencies (Hono, Container, RouteRegistry,
+ * ComponentManager) via constructor — no static state.
+ */
+export declare class RouteManager {
+    private hono;
+    private container;
+    private routeRegistry;
+    private componentManager;
+    private parameterResolver;
+    private pipelineExecutor;
+    private metadataRepository;
+    private logger;
+    private globalPrefix?;
+    private globalVersion?;
+    constructor(hono: Hono, container: DiContainer, routeRegistry: RouteRegistry, componentManager: ComponentManager, metadataRepository: IMetadataRepository, logger?: ILogger, options?: {
+        prefix?: string;
+        version?: number | typeof VERSION_NEUTRAL | number[];
+        debugPipeline?: boolean;
+    });
+    private applyGlobalMiddleware;
+    private normalizePath;
+    private registerRouteHandler;
+    private buildRoutePath;
+    private formatVersionSegment;
+    registerController(controllerClass: Constructor): Promise<void>;
+    private registerRoute;
+}

package/dist/managers/route.manager.js

@@ -0,0 +1,149 @@
+import { VERSION_NEUTRAL } from '../constants';
+import { NoopLogger } from '../loggers';
+import { ComponentManager } from './component.manager';
+import { HandlerInvoker } from './handler.invoker';
+import { ParameterResolver } from './parameter.resolver';
+import { PipelineExecutor } from './pipeline.executor';
+import { RouteRegistry } from '../registries/route.registry';
+import { isNil, isString, normalizePath } from '../utils';
+/**
+ * Manager class for handling route registration in the Honest framework.
+ *
+ * Receives all per-app dependencies (Hono, Container, RouteRegistry,
+ * ComponentManager) via constructor — no static state.
+ */
+export class RouteManager {
+    hono;
+    container;
+    routeRegistry;
+    componentManager;
+    parameterResolver;
+    pipelineExecutor;
+    metadataRepository;
+    logger;
+    globalPrefix;
+    globalVersion;
+    constructor(hono, container, routeRegistry, componentManager, metadataRepository, logger = new NoopLogger(), options = {}) {
+        this.hono = hono;
+        this.container = container;
+        this.routeRegistry = routeRegistry;
+        this.componentManager = componentManager;
+        this.logger = logger;
+        this.parameterResolver = new ParameterResolver(this.componentManager, this.logger, Boolean(options.debugPipeline));
+        this.pipelineExecutor = new PipelineExecutor(this.componentManager, this.parameterResolver, new HandlerInvoker(), this.logger, Boolean(options.debugPipeline));
+        this.metadataRepository = metadataRepository;
+        this.globalPrefix = options.prefix !== undefined ? this.normalizePath(options.prefix) : undefined;
+        this.globalVersion = options.version;
+        this.applyGlobalMiddleware();
+    }
+    applyGlobalMiddleware() {
+        const globalMiddleware = this.componentManager.getGlobalMiddleware();
+        for (const middleware of globalMiddleware) {
+            this.hono.use('*', middleware);
+        }
+    }
+    normalizePath(path) {
+        if (!isString(path)) {
+            throw new Error(`Invalid path: expected a string but received ${typeof path}. Check your @Controller() and route decorator arguments.`);
+        }
+        return normalizePath(path);
+    }
+    registerRouteHandler(method, path, handlerMiddleware, wrapperHandler) {
+        if (handlerMiddleware.length > 0) {
+            this.hono.on(method.toUpperCase(), [path], ...handlerMiddleware, wrapperHandler);
+        }
+        else {
+            this.hono.on(method.toUpperCase(), [path], wrapperHandler);
+        }
+    }
+    buildRoutePath(prefix, version, controllerPath, methodPath) {
+        return normalizePath(`${prefix}${version}${controllerPath}${methodPath}`);
+    }
+    formatVersionSegment(version) {
+        if (isNil(version)) {
+            return '';
+        }
+        return version === VERSION_NEUTRAL ? '' : `/v${String(version)}`;
+    }
+    async registerController(controllerClass) {
+        if (!this.metadataRepository.hasController(controllerClass)) {
+            throw new Error(`Controller ${controllerClass.name} is not decorated with @Controller()`);
+        }
+        const controllerPath = this.metadataRepository.getControllerPath(controllerClass) || '';
+        const controllerOptions = this.metadataRepository.getControllerOptions(controllerClass) || {};
+        const routes = this.metadataRepository.getRoutes(controllerClass) || [];
+        const parameterMetadata = this.metadataRepository.getParameters(controllerClass) || new Map();
+        const contextIndices = this.metadataRepository.getContextIndices(controllerClass) || new Map();
+        const controllerSegment = this.normalizePath(controllerPath);
+        const controllerInstance = this.container.resolve(controllerClass);
+        const effectiveControllerPrefix = controllerOptions.prefix !== undefined ? controllerOptions.prefix : this.globalPrefix;
+        const effectiveControllerVersion = controllerOptions.version !== undefined ? controllerOptions.version : this.globalVersion;
+        if (routes.length === 0) {
+            throw new Error(`Controller ${controllerClass.name} has no route handlers. Add HTTP method decorators like @Get()`);
+        }
+        for (const route of routes) {
+            const { path, method, version: routeVersion, prefix: routePrefix } = route;
+            const effectivePrefix = routePrefix !== undefined ? routePrefix : effectiveControllerPrefix;
+            const prefixSegment = !isNil(effectivePrefix) ? this.normalizePath(effectivePrefix) : '';
+            const effectiveVersion = routeVersion !== undefined ? routeVersion : effectiveControllerVersion;
+            const methodSegment = this.normalizePath(path);
+            if (isNil(effectiveVersion)) {
+                this.registerRoute(controllerInstance, route, parameterMetadata, contextIndices, controllerClass, prefixSegment, '', controllerSegment, methodSegment, method);
+                continue;
+            }
+            if (effectiveVersion === VERSION_NEUTRAL) {
+                this.registerRoute(controllerInstance, route, parameterMetadata, contextIndices, controllerClass, prefixSegment, '', controllerSegment, methodSegment, method);
+                this.registerRoute(controllerInstance, route, parameterMetadata, contextIndices, controllerClass, prefixSegment, '/:version{v[0-9]+}', controllerSegment, methodSegment, method);
+                continue;
+            }
+            if (Array.isArray(effectiveVersion)) {
+                for (const version of effectiveVersion) {
+                    const versionSegment = this.formatVersionSegment(version);
+                    this.registerRoute(controllerInstance, route, parameterMetadata, contextIndices, controllerClass, prefixSegment, versionSegment, controllerSegment, methodSegment, method);
+                }
+                continue;
+            }
+            const versionSegment = this.formatVersionSegment(effectiveVersion);
+            this.registerRoute(controllerInstance, route, parameterMetadata, contextIndices, controllerClass, prefixSegment, versionSegment, controllerSegment, methodSegment, method);
+        }
+    }
+    registerRoute(controllerInstance, route, parameterMetadata, contextIndices, controllerClass, prefixSegment, versionSegment, controllerSegment, methodSegment, method) {
+        const { handlerName } = route;
+        const fullPath = this.buildRoutePath(prefixSegment, versionSegment, controllerSegment, methodSegment);
+        const handler = controllerInstance[handlerName].bind(controllerInstance);
+        const handlerParams = parameterMetadata.get(handlerName) || [];
+        const contextIndex = contextIndices.get(handlerName);
+        const handlerMiddleware = this.componentManager.getHandlerMiddleware(controllerClass, handlerName);
+        const handlerPipes = this.componentManager.getHandlerPipes(controllerClass, handlerName);
+        this.routeRegistry.registerRoute({
+            controller: controllerClass.name,
+            handler: handlerName,
+            method,
+            prefix: prefixSegment,
+            version: versionSegment,
+            route: controllerSegment,
+            path: methodSegment,
+            fullPath,
+            parameters: handlerParams
+        });
+        const componentManager = this.componentManager;
+        const pipelineExecutor = this.pipelineExecutor;
+        const wrapperHandler = async (c) => {
+            try {
+                return await pipelineExecutor.execute({
+                    controllerClass,
+                    handlerName,
+                    handler,
+                    handlerParams,
+                    handlerPipes,
+                    contextIndex,
+                    context: c
+                });
+            }
+            catch (error) {
+                return componentManager.handleException(error, c);
+            }
+        };
+        this.registerRouteHandler(method, fullPath, handlerMiddleware, wrapperHandler);
+    }
+}

package/dist/registries/index.d.ts

@@ -0,0 +1,4 @@
+export * from './metadata.registry';
+export * from './metadata.repository';
+export * from './route.registry';
+export * from './service.registry';

package/dist/registries/index.js

@@ -0,0 +1,4 @@
+export * from './metadata.registry';
+export * from './metadata.repository';
+export * from './route.registry';
+export * from './service.registry';

package/dist/registries/metadata.registry.d.ts

@@ -0,0 +1,163 @@
+import type { ControllerOptions, FilterType, GuardType, MiddlewareType, ModuleOptions, ParameterMetadata, PipeType, RouteDefinition } from '../interfaces';
+import type { Constructor } from '../types';
+export type ComponentType = 'middleware' | 'guard' | 'pipe' | 'filter';
+export type ComponentInstance = MiddlewareType | GuardType | PipeType | FilterType;
+export interface ComponentTypeMap {
+    middleware: MiddlewareType;
+    guard: GuardType;
+    pipe: PipeType;
+    filter: FilterType;
+}
+/**
+ * Central registry for managing application metadata
+ * Stores and provides access to:
+ * - Route definitions and controller configurations
+ * - Service and module registrations
+ * - Parameter metadata and context indices
+ * - Component registrations at global, controller, and handler levels
+ */
+export declare class MetadataRegistry {
+    /**
+     * Stores route definitions for each controller
+     * Maps controller classes to their route configurations
+     */
+    private static readonly routes;
+    /**
+     * Stores base paths for controllers
+     * Maps controller classes to their route prefixes
+     */
+    private static readonly controllers;
+    /**
+     * Stores configuration options for controllers
+     * Includes settings like versioning and prefix options
+     */
+    private static readonly controllerOptions;
+    /**
+     * Registry of service classes
+     * Used for dependency injection and lifecycle management
+     */
+    private static readonly services;
+    /**
+     * Stores configuration options for modules
+     * Includes imports, exports, providers, and controllers
+     */
+    private static readonly modules;
+    /**
+     * Stores parameter metadata for controller methods
+     * Used for parameter transformation and validation
+     */
+    private static readonly parameters;
+    /**
+     * Stores indices of context parameters in controller methods
+     * Used for optimizing context injection
+     */
+    private static readonly contextIndices;
+    /**
+     * Registry for controller-level components
+     * Components registered here apply to all routes in a specific controller
+     */
+    private static readonly controller;
+    /**
+     * Registry for handler-level components
+     * Components registered here apply to specific route handlers
+     * Keyed by controller constructor then handler name for collision-safe lookups
+     */
+    private static readonly handler;
+    /**
+     * Gets all route definitions for a controller
+     * @param controller - The controller class to get routes for
+     * @returns Array of route definitions for the controller
+     */
+    static getRoutes(controller: Constructor): RouteDefinition[];
+    /**
+     * Set routes for a controller
+     */
+    static setRoutes(controller: Constructor, routes: RouteDefinition[]): void;
+    /**
+     * Add a route to a controller
+     */
+    static addRoute(controller: Constructor, route: RouteDefinition): void;
+    /**
+     * Get controller path
+     */
+    static getControllerPath(controller: Constructor): string;
+    /**
+     * Check if a class is registered as a controller.
+     */
+    static hasController(controller: Constructor): boolean;
+    /**
+     * Set controller path
+     */
+    static setControllerPath(controller: Constructor, path: string): void;
+    /**
+     * Get controller options
+     */
+    static getControllerOptions(controller: Constructor): ControllerOptions;
+    /**
+     * Set controller options
+     */
+    static setControllerOptions(controller: Constructor, options: ControllerOptions): void;
+    /**
+     * Check if class is a service
+     */
+    static isService(service: Constructor): boolean;
+    /**
+     * Add a service
+     */
+    static addService(service: Constructor): void;
+    /**
+     * Get all services
+     */
+    static getAllServices(): Set<Constructor>;
+    /**
+     * Get module options
+     */
+    static getModuleOptions(module: Constructor): ModuleOptions | undefined;
+    /**
+     * Set module options
+     */
+    static setModuleOptions(module: Constructor, options: ModuleOptions): void;
+    /**
+     * Get parameter metadata
+     */
+    static getParameters(controller: Constructor): Map<string | symbol, ParameterMetadata[]>;
+    /**
+     * Set parameter metadata
+     */
+    static setParameterMap(controller: Constructor, params: Map<string | symbol, ParameterMetadata[]>): void;
+    /**
+     * Get context indices
+     */
+    static getContextIndices(controller: Constructor): Map<string | symbol, number>;
+    /**
+     * Set context indices
+     */
+    static setContextIndices(controller: Constructor, indices: Map<string | symbol, number>): void;
+    /**
+     * Register a component at the controller level
+     */
+    static registerController<T extends ComponentType>(type: T, controller: Constructor, component: ComponentTypeMap[T]): void;
+    /**
+     * Get all controller-level components of a specific type for a controller
+     */
+    static getController<T extends ComponentType>(type: T, controller: Constructor): ComponentTypeMap[T][];
+    /**
+     * Register a component at the handler level
+     */
+    static registerHandler<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol, component: ComponentTypeMap[T]): void;
+    /**
+     * Get all handler-level components of a specific type for a handler
+     */
+    static getHandler<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol): ComponentTypeMap[T][];
+    /**
+     * Clears handler-level component registrations created via {@link registerHandler}.
+     * Does not remove decorator-defined routes, controllers, or modules.
+     */
+    static clearHandlerComponents(): void;
+    /**
+     * Clears all registered decorator metadata.
+     * Primarily used for testing. Warning: clearing after importing decorated classes
+     * (e.g. shared fixtures) removes their metadata until those modules are re-evaluated.
+     */
+    static clear(): void;
+}