honest-node 1.0.0

package/dist/registries/metadata.registry.js

@@ -0,0 +1,250 @@
+/**
+ * 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 class MetadataRegistry {
+    /**
+     * Stores route definitions for each controller
+     * Maps controller classes to their route configurations
+     */
+    static routes = new Map();
+    /**
+     * Stores base paths for controllers
+     * Maps controller classes to their route prefixes
+     */
+    static controllers = new Map();
+    /**
+     * Stores configuration options for controllers
+     * Includes settings like versioning and prefix options
+     */
+    static controllerOptions = new Map();
+    /**
+     * Registry of service classes
+     * Used for dependency injection and lifecycle management
+     */
+    static services = new Set();
+    /**
+     * Stores configuration options for modules
+     * Includes imports, exports, providers, and controllers
+     */
+    static modules = new Map();
+    /**
+     * Stores parameter metadata for controller methods
+     * Used for parameter transformation and validation
+     */
+    static parameters = new Map();
+    /**
+     * Stores indices of context parameters in controller methods
+     * Used for optimizing context injection
+     */
+    static contextIndices = new Map();
+    /**
+     * Registry for controller-level components
+     * Components registered here apply to all routes in a specific controller
+     */
+    static controller = new Map([
+        ['middleware', new Map()],
+        ['guard', new Map()],
+        ['pipe', new Map()],
+        ['filter', new Map()]
+    ]);
+    /**
+     * Registry for handler-level components
+     * Components registered here apply to specific route handlers
+     * Keyed by controller constructor then handler name for collision-safe lookups
+     */
+    static handler = new Map([
+        ['middleware', new Map()],
+        ['guard', new Map()],
+        ['pipe', new Map()],
+        ['filter', new Map()]
+    ]);
+    /**
+     * 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) {
+        return this.routes.get(controller) || [];
+    }
+    /**
+     * Set routes for a controller
+     */
+    static setRoutes(controller, routes) {
+        this.routes.set(controller, routes);
+    }
+    /**
+     * Add a route to a controller
+     */
+    static addRoute(controller, route) {
+        if (!this.routes.has(controller)) {
+            this.routes.set(controller, []);
+        }
+        this.routes.get(controller).push(route);
+    }
+    /**
+     * Get controller path
+     */
+    static getControllerPath(controller) {
+        return this.controllers.get(controller) || '';
+    }
+    /**
+     * Check if a class is registered as a controller.
+     */
+    static hasController(controller) {
+        return this.controllers.has(controller);
+    }
+    /**
+     * Set controller path
+     */
+    static setControllerPath(controller, path) {
+        this.controllers.set(controller, path);
+    }
+    /**
+     * Get controller options
+     */
+    static getControllerOptions(controller) {
+        return this.controllerOptions.get(controller) || {};
+    }
+    /**
+     * Set controller options
+     */
+    static setControllerOptions(controller, options) {
+        this.controllerOptions.set(controller, options);
+    }
+    /**
+     * Check if class is a service
+     */
+    static isService(service) {
+        return this.services.has(service);
+    }
+    /**
+     * Add a service
+     */
+    static addService(service) {
+        this.services.add(service);
+    }
+    /**
+     * Get all services
+     */
+    static getAllServices() {
+        return this.services;
+    }
+    /**
+     * Get module options
+     */
+    static getModuleOptions(module) {
+        return this.modules.get(module);
+    }
+    /**
+     * Set module options
+     */
+    static setModuleOptions(module, options) {
+        this.modules.set(module, options);
+    }
+    /**
+     * Get parameter metadata
+     */
+    static getParameters(controller) {
+        return this.parameters.get(controller) || new Map();
+    }
+    /**
+     * Set parameter metadata
+     */
+    static setParameterMap(controller, params) {
+        this.parameters.set(controller, params);
+    }
+    /**
+     * Get context indices
+     */
+    static getContextIndices(controller) {
+        return this.contextIndices.get(controller) || new Map();
+    }
+    /**
+     * Set context indices
+     */
+    static setContextIndices(controller, indices) {
+        this.contextIndices.set(controller, indices);
+    }
+    /**
+     * Register a component at the controller level
+     */
+    static registerController(type, controller, component) {
+        const typeMap = this.controller.get(type);
+        if (!typeMap.has(controller)) {
+            typeMap.set(controller, []);
+        }
+        typeMap.get(controller).push(component);
+    }
+    /**
+     * Get all controller-level components of a specific type for a controller
+     */
+    static getController(type, controller) {
+        const typeMap = this.controller.get(type);
+        return (typeMap.get(controller) || []);
+    }
+    /**
+     * Register a component at the handler level
+     */
+    static registerHandler(type, controller, handlerName, component) {
+        const typeMap = this.handler.get(type);
+        if (!typeMap.has(controller)) {
+            typeMap.set(controller, new Map());
+        }
+        const controllerMap = typeMap.get(controller);
+        if (!controllerMap.has(handlerName)) {
+            controllerMap.set(handlerName, []);
+        }
+        controllerMap.get(handlerName).push(component);
+    }
+    /**
+     * Get all handler-level components of a specific type for a handler
+     */
+    static getHandler(type, controller, handlerName) {
+        const typeMap = this.handler.get(type);
+        const controllerMap = typeMap.get(controller);
+        if (!controllerMap) {
+            return [];
+        }
+        return (controllerMap.get(handlerName) || []);
+    }
+    /**
+     * Clears handler-level component registrations created via {@link registerHandler}.
+     * Does not remove decorator-defined routes, controllers, or modules.
+     */
+    static clearHandlerComponents() {
+        for (const typeMap of this.handler.values()) {
+            for (const controllerMap of typeMap.values()) {
+                controllerMap.clear();
+            }
+            typeMap.clear();
+        }
+    }
+    /**
+     * 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() {
+        this.routes.clear();
+        this.controllers.clear();
+        this.controllerOptions.clear();
+        this.services.clear();
+        this.modules.clear();
+        this.parameters.clear();
+        this.contextIndices.clear();
+        for (const map of this.controller.values()) {
+            map.clear();
+        }
+        for (const typeMap of this.handler.values()) {
+            for (const controllerMap of typeMap.values()) {
+                controllerMap.clear();
+            }
+            typeMap.clear();
+        }
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { ControllerOptions, IMetadataRepository, MetadataComponentType, MetadataComponentTypeMap, ModuleOptions, ParameterMetadata, RouteDefinition } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Immutable metadata repository for a single Application instance.
+ * Captures a deep copy of all metadata reachable from a root module at creation time,
+ * isolating the application from later mutations to the static MetadataRegistry.
+ */
+export declare class MetadataRepository implements IMetadataRepository {
+    private readonly controllerPaths;
+    private readonly controllerOptions;
+    private readonly routes;
+    private readonly parameters;
+    private readonly contextIndices;
+    private readonly modules;
+    private readonly controllerComponents;
+    private readonly handlerComponents;
+    static fromRootModule(rootModule: Constructor): MetadataRepository;
+    hasController(controller: Constructor): boolean;
+    getControllerPath(controller: Constructor): string;
+    getControllerOptions(controller: Constructor): ControllerOptions;
+    getRoutes(controller: Constructor): RouteDefinition[];
+    getParameters(controller: Constructor): Map<string | symbol, ParameterMetadata[]>;
+    getContextIndices(controller: Constructor): Map<string | symbol, number>;
+    getModuleOptions(module: Constructor): ModuleOptions | undefined;
+    getControllerComponents<T extends MetadataComponentType>(type: T, controller: Constructor): MetadataComponentTypeMap[T][];
+    getHandlerComponents<T extends MetadataComponentType>(type: T, controller: Constructor, handlerName: string | symbol): MetadataComponentTypeMap[T][];
+    private captureModuleGraph;
+    private captureController;
+    private cloneRouteDefinition;
+}

package/dist/registries/metadata.repository.js

@@ -0,0 +1,151 @@
+import { MetadataRegistry } from './metadata.registry';
+/**
+ * Immutable metadata repository for a single Application instance.
+ * Captures a deep copy of all metadata reachable from a root module at creation time,
+ * isolating the application from later mutations to the static MetadataRegistry.
+ */
+export class MetadataRepository {
+    controllerPaths = new Map();
+    controllerOptions = new Map();
+    routes = new Map();
+    parameters = new Map();
+    contextIndices = new Map();
+    modules = new Map();
+    controllerComponents = new Map([
+        ['middleware', new Map()],
+        ['guard', new Map()],
+        ['pipe', new Map()],
+        ['filter', new Map()]
+    ]);
+    handlerComponents = new Map([
+        ['middleware', new Map()],
+        ['guard', new Map()],
+        ['pipe', new Map()],
+        ['filter', new Map()]
+    ]);
+    static fromRootModule(rootModule) {
+        const snapshot = new MetadataRepository();
+        snapshot.captureModuleGraph(rootModule);
+        return snapshot;
+    }
+    hasController(controller) {
+        return this.controllerPaths.has(controller);
+    }
+    getControllerPath(controller) {
+        return this.controllerPaths.get(controller) || '';
+    }
+    getControllerOptions(controller) {
+        const options = this.controllerOptions.get(controller);
+        return options ? { ...options } : {};
+    }
+    getRoutes(controller) {
+        return (this.routes.get(controller) || []).map((route) => this.cloneRouteDefinition(route));
+    }
+    getParameters(controller) {
+        const parameters = this.parameters.get(controller);
+        if (!parameters) {
+            return new Map();
+        }
+        const cloned = new Map();
+        for (const [handlerName, entries] of parameters.entries()) {
+            cloned.set(handlerName, entries.map((entry) => ({ ...entry })));
+        }
+        return cloned;
+    }
+    getContextIndices(controller) {
+        return new Map(this.contextIndices.get(controller) || new Map());
+    }
+    getModuleOptions(module) {
+        const options = this.modules.get(module);
+        if (!options) {
+            return undefined;
+        }
+        return {
+            controllers: options.controllers ? [...options.controllers] : undefined,
+            services: options.services ? [...options.services] : undefined,
+            imports: options.imports ? [...options.imports] : undefined
+        };
+    }
+    getControllerComponents(type, controller) {
+        const map = this.controllerComponents.get(type);
+        const components = (map.get(controller) || []);
+        return [...components];
+    }
+    getHandlerComponents(type, controller, handlerName) {
+        const typeMap = this.handlerComponents.get(type);
+        const controllerMap = typeMap.get(controller);
+        if (!controllerMap) {
+            return [];
+        }
+        const components = (controllerMap.get(handlerName) || []);
+        return [...components];
+    }
+    captureModuleGraph(rootModule) {
+        const visitedModules = new Set();
+        const controllers = new Set();
+        const visitModule = (moduleClass) => {
+            if (visitedModules.has(moduleClass)) {
+                return;
+            }
+            visitedModules.add(moduleClass);
+            const moduleOptions = MetadataRegistry.getModuleOptions(moduleClass);
+            if (!moduleOptions) {
+                return;
+            }
+            const moduleSnapshot = {
+                controllers: moduleOptions.controllers ? [...moduleOptions.controllers] : undefined,
+                services: moduleOptions.services ? [...moduleOptions.services] : undefined,
+                imports: moduleOptions.imports ? [...moduleOptions.imports] : undefined
+            };
+            this.modules.set(moduleClass, moduleSnapshot);
+            for (const controller of moduleSnapshot.controllers || []) {
+                controllers.add(controller);
+            }
+            for (const importedModule of moduleSnapshot.imports || []) {
+                visitModule(importedModule);
+            }
+        };
+        visitModule(rootModule);
+        for (const controller of controllers) {
+            this.captureController(controller);
+        }
+    }
+    captureController(controller) {
+        if (!MetadataRegistry.hasController(controller)) {
+            return;
+        }
+        this.controllerPaths.set(controller, MetadataRegistry.getControllerPath(controller) || '');
+        this.controllerOptions.set(controller, { ...MetadataRegistry.getControllerOptions(controller) });
+        const routes = (MetadataRegistry.getRoutes(controller) || []).map((route) => this.cloneRouteDefinition(route));
+        this.routes.set(controller, routes);
+        const parameters = MetadataRegistry.getParameters(controller);
+        const parameterSnapshot = new Map();
+        for (const [handlerName, entries] of parameters.entries()) {
+            parameterSnapshot.set(handlerName, (entries || []).map((entry) => ({ ...entry })));
+        }
+        this.parameters.set(controller, parameterSnapshot);
+        this.contextIndices.set(controller, new Map(MetadataRegistry.getContextIndices(controller) || new Map()));
+        for (const type of ['middleware', 'guard', 'pipe', 'filter']) {
+            const controllerMap = this.controllerComponents.get(type);
+            controllerMap.set(controller, [...(MetadataRegistry.getController(type, controller) || [])]);
+        }
+        for (const route of routes) {
+            for (const type of ['middleware', 'guard', 'pipe', 'filter']) {
+                const typeMap = this.handlerComponents.get(type);
+                if (!typeMap.has(controller)) {
+                    typeMap.set(controller, new Map());
+                }
+                const controllerHandlers = typeMap.get(controller);
+                controllerHandlers.set(route.handlerName, [
+                    ...MetadataRegistry.getHandler(type, controller, route.handlerName)
+                ]);
+            }
+        }
+    }
+    cloneRouteDefinition(route) {
+        return {
+            ...route,
+            version: Array.isArray(route.version) ? [...route.version] : route.version
+        };
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { RouteInfo } from '../interfaces';
+/**
+ * Registry for managing and querying route information in the application.
+ *
+ * Each Application instance owns its own RouteRegistry, ensuring routes
+ * from one app never leak into another.
+ */
+export declare class RouteRegistry {
+    private readonly routes;
+    registerRoute(routeInfo: RouteInfo): void;
+    getRoutes(): ReadonlyArray<RouteInfo>;
+    getRoutesByController(controllerName: string | symbol): ReadonlyArray<RouteInfo>;
+    getRoutesByMethod(method: string): ReadonlyArray<RouteInfo>;
+    getRoutesByPath(pattern: RegExp): ReadonlyArray<RouteInfo>;
+    clear(): void;
+}

package/dist/registries/route.registry.js

@@ -0,0 +1,46 @@
+/**
+ * Registry for managing and querying route information in the application.
+ *
+ * Each Application instance owns its own RouteRegistry, ensuring routes
+ * from one app never leak into another.
+ */
+export class RouteRegistry {
+    routes = [];
+    registerRoute(routeInfo) {
+        if (!routeInfo) {
+            throw new Error('Route info is required');
+        }
+        if (!routeInfo.controller) {
+            throw new Error('Route controller is required');
+        }
+        if (!routeInfo.handler) {
+            throw new Error('Route handler is required');
+        }
+        if (!routeInfo.method) {
+            throw new Error('Route method is required');
+        }
+        if (!routeInfo.fullPath) {
+            throw new Error('Route fullPath is required');
+        }
+        const isDuplicate = this.routes.some((route) => route.fullPath === routeInfo.fullPath && route.method.toUpperCase() === routeInfo.method.toUpperCase());
+        if (isDuplicate) {
+            throw new Error(`Duplicate route detected: ${routeInfo.method.toUpperCase()} ${routeInfo.fullPath} (${String(routeInfo.controller)}.${String(routeInfo.handler)})`);
+        }
+        this.routes.push(routeInfo);
+    }
+    getRoutes() {
+        return this.routes;
+    }
+    getRoutesByController(controllerName) {
+        return this.routes.filter((route) => route.controller === controllerName);
+    }
+    getRoutesByMethod(method) {
+        return this.routes.filter((route) => route.method.toUpperCase() === method.toUpperCase());
+    }
+    getRoutesByPath(pattern) {
+        return this.routes.filter((route) => pattern.test(route.fullPath));
+    }
+    clear() {
+        this.routes.length = 0;
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { IServiceRegistry } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Adapter exposing service checks through the DI service registry contract.
+ */
+export declare class StaticServiceRegistry implements IServiceRegistry {
+    isService(service: Constructor): boolean;
+}

package/dist/registries/service.registry.js

@@ -0,0 +1,9 @@
+import { MetadataRegistry } from './metadata.registry';
+/**
+ * Adapter exposing service checks through the DI service registry contract.
+ */
+export class StaticServiceRegistry {
+    isService(service) {
+        return MetadataRegistry.isService(service);
+    }
+}

package/dist/testing/create-controller-test-application.d.ts

@@ -0,0 +1,5 @@
+import type { CreateControllerTestApplicationOptions, TestApplication } from './testing.interface';
+/**
+ * Create a test application for a single controller with optional services/imports.
+ */
+export declare function createControllerTestApplication(options: CreateControllerTestApplicationOptions): Promise<TestApplication>;

package/dist/testing/create-controller-test-application.js

@@ -0,0 +1,11 @@
+import { createTestApplication } from './create-test-application';
+/**
+ * Create a test application for a single controller with optional services/imports.
+ */
+export async function createControllerTestApplication(options) {
+    const { controller, ...rest } = options;
+    return createTestApplication({
+        ...rest,
+        controllers: [controller]
+    });
+}

package/dist/testing/create-service-test-container.d.ts

@@ -0,0 +1,5 @@
+import type { CreateServiceTestContainerOptions, TestServiceContainer } from './testing.interface';
+/**
+ * Create a lightweight DI container for service-only tests without HTTP bootstrap.
+ */
+export declare function createServiceTestContainer(options?: CreateServiceTestContainerOptions): TestServiceContainer;

package/dist/testing/create-service-test-container.js

@@ -0,0 +1,31 @@
+import { NoopLogger } from '../loggers';
+import { Container } from '../di';
+/**
+ * Create a lightweight DI container for service-only tests without HTTP bootstrap.
+ */
+export function createServiceTestContainer(options = {}) {
+    const logger = options.logger ?? new NoopLogger();
+    const container = new Container(undefined, logger, Boolean(options.debugDi));
+    for (const override of options.overrides ?? []) {
+        const typedOverride = override;
+        container.register(typedOverride.provide, typedOverride.useValue);
+    }
+    for (const service of options.preload ?? []) {
+        container.resolve(service);
+    }
+    return {
+        container,
+        get(target) {
+            return container.resolve(target);
+        },
+        register(target, instance) {
+            container.register(target, instance);
+        },
+        has(target) {
+            return container.has(target);
+        },
+        clear() {
+            container.clear();
+        }
+    };
+}

package/dist/testing/create-test-application.d.ts

@@ -0,0 +1,5 @@
+import type { CreateTestApplicationOptions, TestApplication } from './testing.interface';
+/**
+ * Create a test-friendly application instance with a convenience request helper.
+ */
+export declare function createTestApplication(options?: CreateTestApplicationOptions): Promise<TestApplication>;

package/dist/testing/create-test-application.js

@@ -0,0 +1,20 @@
+import { Application } from '../application';
+import { createTestingModule } from './create-testing-module';
+/**
+ * Create a test-friendly application instance with a convenience request helper.
+ */
+export async function createTestApplication(options = {}) {
+    const { module, appOptions, ...moduleOptions } = options;
+    const rootModule = (module ?? createTestingModule(moduleOptions));
+    const { app, hono } = await Application.create(rootModule, appOptions);
+    const request = (input, init) => {
+        if (typeof input === 'string') {
+            const normalizedInput = input.startsWith('http://') || input.startsWith('https://')
+                ? input
+                : `http://localhost${input.startsWith('/') ? input : `/${input}`}`;
+            return Promise.resolve(hono.request(normalizedInput, init));
+        }
+        return Promise.resolve(hono.request(input));
+    };
+    return { app, hono, request };
+}

package/dist/testing/create-testing-module.d.ts

@@ -0,0 +1,6 @@
+import type { Constructor } from '../types';
+import type { TestModuleOptions } from './testing.interface';
+/**
+ * Create a runtime module class for tests without boilerplate.
+ */
+export declare function createTestingModule(options?: TestModuleOptions): Constructor;

package/dist/testing/create-testing-module.js

@@ -0,0 +1,13 @@
+import { Module } from '../decorators';
+/**
+ * Create a runtime module class for tests without boilerplate.
+ */
+export function createTestingModule(options = {}) {
+    const { controllers, services, imports, name = 'TestModule' } = options;
+    const dynamicModule = {
+        [name]: class {
+        }
+    }[name];
+    Module({ controllers, services, imports })(dynamicModule);
+    return dynamicModule;
+}

package/dist/testing/fixtures/application-test-fixtures.d.ts

@@ -0,0 +1,17 @@
+import type { Constructor } from '../../types';
+export declare function createTestController(): Constructor;
+export declare function createPayloadController(): Constructor;
+export declare function createRawResponseController(): Constructor;
+export declare function createOnlyAController(): Constructor;
+export declare function createOnlyBController(): Constructor;
+export declare function createUndecoratedController(): Constructor;
+export declare function createBrokenControllerModule(): Constructor;
+export declare function createEmptyModule(): Constructor;
+export declare function createDuplicateRouteControllers(): {
+    a: Constructor;
+    b: Constructor;
+};
+export declare function createUnsafeParamController(): Constructor;
+export declare function createDiagnosticsAController(): Constructor;
+export declare function createDiagnosticsBController(): Constructor;
+export declare function createRuntimeMetadataController(): Constructor;