honest-node 1.0.0

package/dist/interfaces/parameter-metadata.interface.d.ts

@@ -0,0 +1,27 @@
+import type { Constructor } from '../types';
+import type { Context } from 'hono';
+/**
+ * Metadata for route parameters
+ */
+export interface ParameterMetadata {
+    /**
+     * Parameter index
+     */
+    index: number;
+    /**
+     * Parameter name (body, param, query, etc.)
+     */
+    name: string;
+    /**
+     * Additional parameter data (e.g., param name)
+     */
+    data?: unknown;
+    /**
+     * Optional factory function to transform the data
+     */
+    factory: (data: unknown, ctx: Context) => unknown | Promise<unknown>;
+    /**
+     * The class type of the parameter
+     */
+    metatype?: Constructor<unknown>;
+}

package/dist/interfaces/parameter-metadata.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/parameter-resolution.interface.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from 'hono';
+import type { IPipe } from './pipe.interface';
+import type { ParameterMetadata } from './parameter-metadata.interface';
+/**
+ * Input contract for route-parameter resolution.
+ */
+export interface ParameterResolutionInput {
+    controllerName: string;
+    handlerName: string | symbol;
+    handlerArity: number;
+    handlerParams: ReadonlyArray<ParameterMetadata>;
+    handlerPipes: ReadonlyArray<IPipe>;
+    context: Context;
+}

package/dist/interfaces/parameter-resolution.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/pipe.interface.d.ts

@@ -0,0 +1,37 @@
+import type { Constructor } from '../types';
+/**
+ * Metadata about an argument being processed by a pipe
+ */
+export interface ArgumentMetadata {
+    /**
+     * The type of argument (body, query, param, header, request, response, context, variable, or custom)
+     */
+    type: 'body' | 'query' | 'param' | 'header' | 'request' | 'response' | 'context' | 'variable' | string;
+    /**
+     * The class type of the argument
+     */
+    metatype?: Constructor<unknown>;
+    /**
+     * Additional data about the argument
+     */
+    data?: string;
+}
+/**
+ * Interface for transformation pipes
+ * Pipes transform input data before it reaches the route handler
+ */
+export interface IPipe {
+    /**
+     * Transforms the input value according to the pipe's logic
+     * @param value - The value to transform
+     * @param metadata - Metadata about the argument being transformed
+     * @returns The transformed value, which can be synchronous or asynchronous
+     * @throws {Error} If the transformation fails or validation fails
+     */
+    transform(value: unknown, metadata: ArgumentMetadata): Promise<unknown> | unknown;
+}
+/**
+ * Type for pipe implementations
+ * Can be either a class implementing IPipe or an instance of IPipe
+ */
+export type PipeType = Constructor<IPipe> | IPipe;

package/dist/interfaces/pipe.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/pipeline-context.interface.d.ts

@@ -0,0 +1,9 @@
+import type { Constructor } from '../types';
+/**
+ * Request-scoped keys used by the framework pipeline.
+ */
+export interface PipelineContextValues {
+    controllerClass?: Constructor;
+    handlerName?: string;
+    bodyCache?: unknown;
+}

package/dist/interfaces/pipeline-context.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/plugin.interface.d.ts

@@ -0,0 +1,74 @@
+import type { Hono } from 'hono';
+import type { Application } from '../application';
+import type { IApplicationContext } from './application-context.interface';
+import type { ILogger } from './logger.interface';
+import type { Constructor } from '../types';
+/**
+ * Processor callback for plugin pre/post hooks.
+ * Receives app, hono, and the application context (registry) for sharing pipeline data.
+ */
+export type PluginProcessor = (app: Application, hono: Hono, ctx: IApplicationContext) => void | Promise<void>;
+/**
+ * Optional metadata for plugin diagnostics.
+ */
+export interface PluginMeta {
+    /**
+     * Stable plugin name used for diagnostics.
+     */
+    name?: string;
+}
+/**
+ * Object form of a plugin entry with optional pre/post processors.
+ * Processors run before (pre) or after (post) the plugin's lifecycle hooks.
+ */
+export interface PluginEntryObject {
+    plugin: IPlugin | Constructor<IPlugin>;
+    /**
+     * Optional stable plugin name for diagnostics.
+     * Takes precedence over plugin.meta.name.
+     */
+    name?: string;
+    preProcessors?: PluginProcessor[];
+    postProcessors?: PluginProcessor[];
+}
+/**
+ * Interface for Honest framework plugins
+ * Plugins can extend the framework's functionality by hooking into
+ * different stages of the application lifecycle
+ */
+export interface IPlugin {
+    /**
+     * Optional metadata for plugin diagnostics.
+     */
+    meta?: PluginMeta;
+    /**
+     * Application logger, injected by the framework before lifecycle hooks run.
+     * Use this to emit structured log events from within plugin code.
+     */
+    logger?: ILogger;
+    /**
+     * Hook that runs before module registration begins.
+     * Use this to set up plugin functionality that modules might depend on.
+     * @param app - The Honest application instance
+     * @param hono - The underlying Hono application instance
+     */
+    beforeModulesRegistered?: (app: Application, hono: Hono) => void | Promise<void>;
+    /**
+     * Hook that runs after all modules have been registered.
+     * Use this to perform cleanup or setup that requires all modules to be ready.
+     * @param app - The Honest application instance
+     * @param hono - The underlying Hono application instance
+     */
+    afterModulesRegistered?: (app: Application, hono: Hono) => void | Promise<void>;
+}
+/**
+ * Type for plugin implementations
+ * Can be either a class implementing IPlugin or an instance of IPlugin
+ */
+export type PluginType = Constructor<IPlugin> | IPlugin;
+/**
+ * Plugin entry: either a plain plugin or an object wrapping a plugin with optional processors.
+ * Use the object form to attach preProcessors (run before lifecycle hooks) and postProcessors
+ * (run after). Processors receive (app, hono, ctx) where ctx is the application context.
+ */
+export type PluginEntry = PluginType | PluginEntryObject;

package/dist/interfaces/plugin.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/route-definition.interface.d.ts

@@ -0,0 +1,51 @@
+import type { VERSION_NEUTRAL } from '../constants';
+/**
+ * Internal metadata for defining a route. This interface is used by the framework
+ * to store route information collected from decorators.
+ *
+ * @example
+ * ```typescript
+ * // Internal representation of:
+ * @Controller('users')
+ * class UsersController {
+ *   @Get(':id')
+ *   getUser(@Param('id') id: string) {}
+ * }
+ * ```
+ */
+export interface RouteDefinition {
+    /**
+     * Route path relative to the controller's base path.
+     * Supports path parameters using colon syntax.
+     *
+     * @example ':id' | 'users/:userId/posts/:postId' | ''
+     */
+    path: string;
+    /**
+     * HTTP method for the route (GET, POST, PUT, DELETE, etc.)
+     */
+    method: string;
+    /**
+     * Name of the method in the controller class that handles this route
+     */
+    handlerName: string | symbol;
+    /**
+     * Route-specific API version, overrides controller and global version.
+     *
+     * @example
+     * ```typescript
+     * version: 1              // -> /v1/...
+     * version: null          // -> /... (no version)
+     * version: VERSION_NEUTRAL // -> Both /... and /v1/...
+     * version: [1, 2]       // -> Both /v1/... and /v2/...
+     * ```
+     */
+    version?: number | null | typeof VERSION_NEUTRAL | number[];
+    /**
+     * Route-specific prefix that overrides controller and global prefix.
+     * Set to null to explicitly remove any prefix.
+     *
+     * @example 'api' | 'v2/api' | null
+     */
+    prefix?: string | null;
+}

package/dist/interfaces/route-definition.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/route-info.interface.d.ts

@@ -0,0 +1,42 @@
+import type { ParameterMetadata } from './parameter-metadata.interface';
+/**
+ * Route information for registered routes
+ */
+export interface RouteInfo {
+    /**
+     * Controller name
+     */
+    controller: string | symbol;
+    /**
+     * Handler method name
+     */
+    handler: string | symbol;
+    /**
+     * HTTP method
+     */
+    method: string;
+    /**
+     * Effective prefix
+     */
+    prefix: string;
+    /**
+     * Effective version
+     */
+    version?: string;
+    /**
+     * Controller route path
+     */
+    route: string;
+    /**
+     * Method path
+     */
+    path: string;
+    /**
+     * Complete path (prefix + version + route + path)
+     */
+    fullPath: string;
+    /**
+     * Parameter metadata for the handler
+     */
+    parameters: ParameterMetadata[];
+}

package/dist/interfaces/route-info.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/service-registry.interface.d.ts

@@ -0,0 +1,7 @@
+import type { Constructor } from '../types';
+/**
+ * Contract for checking whether classes are registered as injectable services.
+ */
+export interface IServiceRegistry {
+    isService(service: Constructor): boolean;
+}

package/dist/interfaces/service-registry.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/loggers/console.logger.d.ts

@@ -0,0 +1,7 @@
+import type { LogEvent, ILogger } from '../interfaces';
+/**
+ * Default logger that writes structured events to console.
+ */
+export declare class ConsoleLogger implements ILogger {
+    emit(event: LogEvent): void;
+}

package/dist/loggers/console.logger.js

@@ -0,0 +1,21 @@
+/**
+ * Default logger that writes structured events to console.
+ */
+export class ConsoleLogger {
+    emit(event) {
+        const prefix = `[HonestJS:${event.category}]`;
+        const payload = event.details ? [prefix, event.message, event.details] : [prefix, event.message];
+        switch (event.level) {
+            case 'debug':
+            case 'info':
+                console.info(...payload);
+                break;
+            case 'warn':
+                console.warn(...payload);
+                break;
+            case 'error':
+                console.error(...payload);
+                break;
+        }
+    }
+}

package/dist/loggers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './console.logger';
+export * from './noop.logger';

package/dist/loggers/index.js

@@ -0,0 +1,2 @@
+export * from './console.logger';
+export * from './noop.logger';

package/dist/loggers/noop.logger.d.ts

@@ -0,0 +1,7 @@
+import type { LogEvent, ILogger } from '../interfaces';
+/**
+ * Logger implementation that intentionally does nothing.
+ */
+export declare class NoopLogger implements ILogger {
+    emit(_event: LogEvent): void;
+}

package/dist/loggers/noop.logger.js

@@ -0,0 +1,8 @@
+/**
+ * Logger implementation that intentionally does nothing.
+ */
+export class NoopLogger {
+    emit(_event) {
+        // no-op
+    }
+}

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

@@ -0,0 +1,48 @@
+import type { Context, Next } from 'hono';
+import type { ArgumentMetadata, DiContainer, FilterType, GuardType, ILogger, IMetadataRepository, IGuard, IPipe, MiddlewareType, PipeType } from '../interfaces';
+import { type ComponentType, type ComponentTypeMap } from '../registries';
+import type { Constructor } from '../types';
+/**
+ * Manager class for handling all component types in the Honest framework.
+ *
+ * Each Application instance owns a ComponentManager, which holds per-app
+ * global components and a reference to the DI container. Controller-level
+ * and handler-level components remain in MetadataRegistry (static, set at
+ * class-definition time by decorators).
+ */
+export declare class ComponentManager {
+    private readonly container;
+    private readonly metadataRepository;
+    private readonly logger;
+    private readonly globalComponents;
+    constructor(container: DiContainer, metadataRepository: IMetadataRepository, logger?: ILogger);
+    /**
+     * Configures global components from application options.
+     */
+    setupGlobalComponents(options: {
+        components?: {
+            middleware?: MiddlewareType[];
+            guards?: GuardType[];
+            pipes?: PipeType[];
+            filters?: FilterType[];
+        };
+    }): void;
+    registerGlobal<T extends ComponentType>(type: T, ...components: ComponentTypeMap[T][]): void;
+    getGlobal<T extends ComponentType>(type: T): Set<ComponentTypeMap[T]>;
+    /**
+     * Gets all components of a specific type for a handler.
+     * Merges: instance global → static controller → static handler.
+     */
+    getComponents<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol): ComponentTypeMap[T][];
+    resolveMiddleware(middlewareItems: MiddlewareType[]): ((c: Context, next: Next) => Promise<Response | void>)[];
+    getHandlerMiddleware(controller: Constructor, handlerName: string | symbol): ((c: Context, next: Next) => Promise<Response | void>)[];
+    getGlobalMiddleware(): ((c: Context, next: Next) => Promise<Response | void>)[];
+    resolveGuards(guardItems: GuardType[]): IGuard[];
+    getHandlerGuards(controller: Constructor, handlerName: string | symbol): IGuard[];
+    resolvePipes(pipeItems: PipeType[]): IPipe[];
+    getHandlerPipes(controller: Constructor, handlerName: string | symbol): IPipe[];
+    executePipes(value: unknown, metadata: ArgumentMetadata, pipes: ReadonlyArray<IPipe>): Promise<unknown>;
+    handleException(exception: unknown, context: Context): Promise<Response | undefined>;
+    private executeFilters;
+    registerModule(moduleClass: Constructor, registered?: Set<Constructor>): Promise<Constructor[]>;
+}

package/dist/managers/component.manager.js

@@ -0,0 +1,210 @@
+import { HONEST_PIPELINE_CONTROLLER_KEY, HONEST_PIPELINE_HANDLER_KEY } from '../constants';
+import { createErrorResponse } from '../helpers';
+import { NoopLogger } from '../loggers';
+import {} from '../registries';
+import { isObject } from '../utils';
+/**
+ * Manager class for handling all component types in the Honest framework.
+ *
+ * Each Application instance owns a ComponentManager, which holds per-app
+ * global components and a reference to the DI container. Controller-level
+ * and handler-level components remain in MetadataRegistry (static, set at
+ * class-definition time by decorators).
+ */
+export class ComponentManager {
+    container;
+    metadataRepository;
+    logger;
+    globalComponents = new Map([
+        ['middleware', new Set()],
+        ['guard', new Set()],
+        ['pipe', new Set()],
+        ['filter', new Set()]
+    ]);
+    constructor(container, metadataRepository, logger = new NoopLogger()) {
+        this.container = container;
+        this.metadataRepository = metadataRepository;
+        this.logger = logger;
+    }
+    /**
+     * Configures global components from application options.
+     */
+    setupGlobalComponents(options) {
+        const components = options.components || {};
+        if (components.middleware) {
+            this.registerGlobal('middleware', ...components.middleware);
+        }
+        if (components.guards) {
+            this.registerGlobal('guard', ...components.guards);
+        }
+        if (components.pipes) {
+            this.registerGlobal('pipe', ...components.pipes);
+        }
+        if (components.filters) {
+            this.registerGlobal('filter', ...components.filters);
+        }
+    }
+    registerGlobal(type, ...components) {
+        components.forEach((component) => {
+            this.globalComponents.get(type).add(component);
+        });
+    }
+    getGlobal(type) {
+        return this.globalComponents.get(type);
+    }
+    /**
+     * Gets all components of a specific type for a handler.
+     * Merges: instance global → static controller → static handler.
+     */
+    getComponents(type, controller, handlerName) {
+        const handlerComponents = this.metadataRepository.getHandlerComponents(type, controller, handlerName);
+        const controllerComponents = this.metadataRepository.getControllerComponents(type, controller);
+        const globalComponents = Array.from(this.globalComponents.get(type) || []);
+        return [...globalComponents, ...controllerComponents, ...handlerComponents];
+    }
+    // -- Middleware --
+    resolveMiddleware(middlewareItems) {
+        return middlewareItems.map((middlewareItem) => {
+            if (isObject(middlewareItem) && 'use' in middlewareItem) {
+                return middlewareItem.use.bind(middlewareItem);
+            }
+            const middleware = this.container.resolve(middlewareItem);
+            return middleware.use.bind(middleware);
+        });
+    }
+    getHandlerMiddleware(controller, handlerName) {
+        const controllerMiddleware = this.metadataRepository.getControllerComponents('middleware', controller);
+        const handlerMiddleware = this.metadataRepository.getHandlerComponents('middleware', controller, handlerName);
+        return this.resolveMiddleware([...controllerMiddleware, ...handlerMiddleware]);
+    }
+    getGlobalMiddleware() {
+        const globalMiddleware = Array.from(this.globalComponents.get('middleware') || []);
+        return this.resolveMiddleware(globalMiddleware);
+    }
+    // -- Guards --
+    resolveGuards(guardItems) {
+        return guardItems.map((guardItem) => {
+            if (isObject(guardItem) && 'canActivate' in guardItem) {
+                return guardItem;
+            }
+            return this.container.resolve(guardItem);
+        });
+    }
+    getHandlerGuards(controller, handlerName) {
+        const guardItems = this.getComponents('guard', controller, handlerName);
+        return this.resolveGuards(guardItems);
+    }
+    // -- Pipes --
+    resolvePipes(pipeItems) {
+        return pipeItems.map((pipeItem) => {
+            if (isObject(pipeItem) && 'transform' in pipeItem) {
+                return pipeItem;
+            }
+            return this.container.resolve(pipeItem);
+        });
+    }
+    getHandlerPipes(controller, handlerName) {
+        const pipeItems = this.getComponents('pipe', controller, handlerName);
+        return this.resolvePipes(pipeItems);
+    }
+    async executePipes(value, metadata, pipes) {
+        let transformedValue = value;
+        for (const pipe of pipes) {
+            transformedValue = await pipe.transform(transformedValue, metadata);
+        }
+        return transformedValue;
+    }
+    // -- Filters --
+    async handleException(exception, context) {
+        const normalizedException = exception instanceof Error ? exception : new Error(String(exception));
+        const controller = context.get(HONEST_PIPELINE_CONTROLLER_KEY);
+        const handlerName = context.get(HONEST_PIPELINE_HANDLER_KEY);
+        if (controller && handlerName) {
+            const handlerFilters = this.metadataRepository.getHandlerComponents('filter', controller, handlerName);
+            if (handlerFilters.length > 0) {
+                const response = await this.executeFilters(handlerFilters, normalizedException, context);
+                if (response)
+                    return response;
+            }
+        }
+        if (controller) {
+            const controllerFilters = this.metadataRepository.getControllerComponents('filter', controller);
+            if (controllerFilters.length > 0) {
+                const response = await this.executeFilters(controllerFilters, normalizedException, context);
+                if (response)
+                    return response;
+            }
+        }
+        const globalFilters = Array.from(this.globalComponents.get('filter') || []);
+        if (globalFilters.length > 0) {
+            const response = await this.executeFilters(globalFilters, normalizedException, context);
+            if (response)
+                return response;
+        }
+        const { response, status } = createErrorResponse(normalizedException, context);
+        return context.json(response, status);
+    }
+    async executeFilters(filterItems, exception, context) {
+        for (const filterItem of filterItems) {
+            let filter;
+            if (isObject(filterItem) && 'catch' in filterItem) {
+                filter = filterItem;
+            }
+            else {
+                filter = this.container.resolve(filterItem);
+            }
+            try {
+                const result = await filter.catch(exception, context);
+                if (result !== undefined) {
+                    return result;
+                }
+            }
+            catch (filterError) {
+                const filterName = filter.constructor?.name || 'UnknownFilter';
+                this.logger.emit({
+                    level: 'error',
+                    category: 'errors',
+                    message: `Error in exception filter ${filterName}`,
+                    details: {
+                        error: filterError instanceof Error ? filterError.message : String(filterError)
+                    }
+                });
+                const { response, status } = createErrorResponse(filterError, context);
+                return context.json(response, status);
+            }
+        }
+        return undefined;
+    }
+    // -- Module registration --
+    async registerModule(moduleClass, registered = new Set()) {
+        if (registered.has(moduleClass)) {
+            return [];
+        }
+        registered.add(moduleClass);
+        const moduleOptions = this.metadataRepository.getModuleOptions(moduleClass);
+        if (!moduleOptions) {
+            this.logger.emit({
+                level: 'error',
+                category: 'startup',
+                message: `Module ${moduleClass.name} is not properly decorated with @Module()`
+            });
+            throw new Error(`Module ${moduleClass.name} is not properly decorated with @Module()`);
+        }
+        const controllers = [];
+        if (moduleOptions.imports && moduleOptions.imports.length > 0) {
+            for (const importedModule of moduleOptions.imports) {
+                const importedControllers = await this.registerModule(importedModule, registered);
+                controllers.push(...importedControllers);
+            }
+        }
+        if (moduleOptions.services && moduleOptions.services.length > 0) {
+            for (const serviceClass of moduleOptions.services) {
+                this.container.resolve(serviceClass);
+            }
+        }
+        if (moduleOptions.controllers && moduleOptions.controllers.length > 0) {
+            controllers.push(...moduleOptions.controllers);
+        }
+        return controllers;
+    }
+}

package/dist/managers/handler.invoker.d.ts

@@ -0,0 +1,7 @@
+import type { HandlerInvocationInput } from '../interfaces';
+/**
+ * Invokes route handlers and maps non-Response results to Hono responses.
+ */
+export declare class HandlerInvoker {
+    invoke({ handler, args, context, contextIndex }: HandlerInvocationInput): Promise<unknown>;
+}

package/dist/managers/handler.invoker.js

@@ -0,0 +1,37 @@
+import { FrameworkError } from '../errors';
+import { isNil, isString } from '../utils';
+/**
+ * Invokes route handlers and maps non-Response results to Hono responses.
+ */
+export class HandlerInvoker {
+    async invoke({ handler, args, context, contextIndex }) {
+        const result = await handler(...args);
+        if (contextIndex !== undefined) {
+            return result;
+        }
+        if (result instanceof Response) {
+            return result;
+        }
+        if (isNil(result)) {
+            return context.json(null);
+        }
+        if (isString(result)) {
+            return context.text(result);
+        }
+        try {
+            return context.json(result);
+        }
+        catch (error) {
+            throw new FrameworkError('Handler return value could not be serialized as JSON.', {
+                status: 500,
+                code: 'RESPONSE_SERIALIZATION_FAILED',
+                category: 'pipeline',
+                remediation: 'Return JSON-serializable values from handlers or map custom values in a filter before returning.',
+                details: {
+                    handlerResultType: typeof result
+                },
+                cause: error
+            });
+        }
+    }
+}

package/dist/managers/index.d.ts

@@ -0,0 +1,5 @@
+export * from './component.manager';
+export * from './handler.invoker';
+export * from './parameter.resolver';
+export * from './pipeline.executor';
+export * from './route.manager';

package/dist/managers/index.js

@@ -0,0 +1,5 @@
+export * from './component.manager';
+export * from './handler.invoker';
+export * from './parameter.resolver';
+export * from './pipeline.executor';
+export * from './route.manager';