honest-node 1.0.0

package/dist/helpers/create-http-method-decorator.helper.js

@@ -0,0 +1,30 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Creates a decorator factory for HTTP method handlers
+ * @param method - The HTTP method type (GET, POST, PUT, etc.)
+ * @returns A method decorator factory that accepts a path and options
+ * @example
+ * ```ts
+ * const Get = createHttpMethodDecorator(HttpMethod.GET);
+ *
+ * class Controller {
+ *   @Get('/users')
+ *   getUsers() { }
+ * }
+ * ```
+ */
+export function createHttpMethodDecorator(method) {
+    return (path = '', options = {}) => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        return (target, propertyKey, descriptor) => {
+            const controllerClass = target.constructor;
+            MetadataRegistry.addRoute(controllerClass, {
+                path,
+                method,
+                handlerName: propertyKey,
+                version: options.version,
+                prefix: options.prefix
+            });
+        };
+    };
+}

package/dist/helpers/create-param-decorator.helper.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'hono';
+/**
+ * Creates a parameter decorator factory for route handlers
+ * @template T - The type of the parameter value after transformation
+ * @param type - The type identifier for the parameter
+ * @param factory - Optional function to transform the parameter value
+ * @returns A parameter decorator function that registers parameter metadata
+ * @example
+ * ```ts
+ * const Body = createParamDecorator('body', async (data, ctx) => {
+ *   const body = await ctx.req.json();
+ *   return data ? body[data] : body;
+ * });
+ * ```
+ */
+export declare function createParamDecorator<T = unknown>(type: string, factory?: (data: unknown, ctx: Context) => T | Promise<T>): (data?: unknown) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;

package/dist/helpers/create-param-decorator.helper.js

@@ -0,0 +1,60 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Creates a parameter decorator factory for route handlers
+ * @template T - The type of the parameter value after transformation
+ * @param type - The type identifier for the parameter
+ * @param factory - Optional function to transform the parameter value
+ * @returns A parameter decorator function that registers parameter metadata
+ * @example
+ * ```ts
+ * const Body = createParamDecorator('body', async (data, ctx) => {
+ *   const body = await ctx.req.json();
+ *   return data ? body[data] : body;
+ * });
+ * ```
+ */
+export function createParamDecorator(type, factory) {
+    const fallbackFactory = (data, ctx) => {
+        // Safe default when a custom decorator doesn't provide a factory.
+        // Returning context keeps the value usable and avoids hard runtime crashes.
+        if (data === undefined) {
+            return ctx;
+        }
+        return ctx.get(String(data));
+    };
+    return (data) => {
+        // eslint-disable-next-line @typescript-eslint/no-wrapper-object-types
+        return (target, propertyKey, parameterIndex) => {
+            const controllerClass = target.constructor;
+            // Initialize parameters map for the controller if not exists
+            if (!MetadataRegistry.getParameters(controllerClass).size) {
+                MetadataRegistry.setParameterMap(controllerClass, new Map());
+            }
+            const parametersMap = MetadataRegistry.getParameters(controllerClass);
+            // Initialize parameter metadata array for the method if not exists
+            if (!parametersMap.has(propertyKey)) {
+                parametersMap.set(propertyKey, []);
+            }
+            // Get the parameter type from the method signature using reflect-metadata
+            const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+            const metatype = paramTypes?.[parameterIndex];
+            // Add parameter metadata
+            const parameters = parametersMap.get(propertyKey);
+            parameters.push({
+                index: parameterIndex,
+                name: type,
+                data,
+                factory: (factory || fallbackFactory),
+                metatype
+            });
+            // If it's a context parameter, track its index
+            if (type === 'context') {
+                if (!MetadataRegistry.getContextIndices(controllerClass).size) {
+                    MetadataRegistry.setContextIndices(controllerClass, new Map());
+                }
+                const contextIndices = MetadataRegistry.getContextIndices(controllerClass);
+                contextIndices.set(propertyKey, parameterIndex);
+            }
+        };
+    };
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './create-error-response.helper';
+export * from './create-http-method-decorator.helper';
+export * from './create-param-decorator.helper';

package/dist/helpers/index.js

@@ -0,0 +1,3 @@
+export * from './create-error-response.helper';
+export * from './create-http-method-decorator.helper';
+export * from './create-param-decorator.helper';

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import 'reflect-metadata';
+export * from './application';
+export * from './application-context';
+export * from './components';
+export * from './constants';
+export * from './decorators';
+export * from './loggers';
+export * from './di';
+export * from './errors';
+export * from './handlers';
+export * from './helpers';
+export * from './interfaces';
+export * from './registries';
+export * from './testing';
+export * from './types';
+export * from './utils';

package/dist/index.js

@@ -0,0 +1,16 @@
+import 'reflect-metadata';
+export * from './application';
+export * from './application-context';
+export * from './components';
+export * from './constants';
+export * from './decorators';
+export * from './loggers';
+export * from './di';
+export * from './errors';
+export * from './handlers';
+export * from './helpers';
+export * from './interfaces';
+export * from './registries';
+export * from './testing';
+export * from './types';
+export * from './utils';

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

@@ -0,0 +1,35 @@
+/**
+ * App-level registry where your application can publish and read pipeline data by key.
+ * Available to bootstrap code, services, and any code with access to `app`.
+ * Enables composition without hard coupling: producers and consumers use namespaced keys.
+ */
+export interface IApplicationContext {
+    /**
+     * Get a value by key. Caller provides type for type safety.
+     * @param key - Namespaced registry key (e.g. 'app.config', 'openapi.spec')
+     * @returns The value or undefined if not set
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a value by key.
+     * @param key - Namespaced registry key
+     * @param value - Value to store
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Check if a key is present.
+     * @param key - Registry key
+     * @returns true if the key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a key and its value.
+     * @param key - Registry key
+     * @returns true if the key existed and was removed
+     */
+    delete(key: string): boolean;
+    /**
+     * Iterate over all registered keys.
+     */
+    keys(): IterableIterator<string>;
+}

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

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

package/dist/interfaces/controller-options.interface.d.ts

@@ -0,0 +1,17 @@
+import type { VERSION_NEUTRAL } from '../constants';
+/**
+ * Interface for controller configuration options
+ */
+export interface ControllerOptions {
+    /**
+     * API prefix for this controller's routes, overrides global prefix
+     */
+    prefix?: string | null;
+    /**
+     * API version for this controller's routes (e.g. 1 becomes /v1), overrides global version
+     * Set to null to explicitly opt out of versioning even when global version is set
+     * Set to VERSION_NEUTRAL to make routes accessible both with and without version prefix
+     * Set to an array of numbers to make routes available at multiple versions
+     */
+    version?: number | null | typeof VERSION_NEUTRAL | number[];
+}

package/dist/interfaces/controller-options.interface.js

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

package/dist/interfaces/di-container.interface.d.ts

@@ -0,0 +1,35 @@
+import type { Constructor } from '../types';
+/**
+ * Interface for dependency injection containers
+ * Defines the contract that DI containers must implement to work with the Honest framework
+ * Handles the creation and management of dependency instances
+ */
+export interface DiContainer {
+    /**
+     * Resolves a dependency from the container
+     * Creates a new instance or returns an existing one based on the container's configuration
+     * @param target - The class constructor to resolve
+     * @returns An instance of the requested class with all dependencies injected
+     * @throws {Error} If the dependency cannot be resolved
+     */
+    resolve<T>(target: Constructor<T>): T;
+    /**
+     * Registers a pre-created instance in the container
+     * Used for singleton instances or mocks in testing
+     * @param target - The class constructor to register the instance for
+     * @param instance - The pre-created instance to use
+     * @throws {Error} If registration fails
+     */
+    register<T>(target: Constructor<T>, instance: T): void;
+    /**
+     * Checks whether the container already holds an instance for the given class
+     * @param target - The class constructor to check
+     * @returns true if an instance has been resolved or registered
+     */
+    has<T>(target: Constructor<T>): boolean;
+    /**
+     * Removes all cached instances from the container
+     * Useful for resetting state between tests
+     */
+    clear(): void;
+}

package/dist/interfaces/di-container.interface.js

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

package/dist/interfaces/error-response.interface.d.ts

@@ -0,0 +1,13 @@
+export interface ErrorResponse {
+    status: number;
+    message: string;
+    timestamp: string;
+    path: string;
+    requestId?: string;
+    code?: string;
+    details?: Record<string, any>;
+    errors?: Array<{
+        property: string;
+        constraints: Record<string, string>;
+    }>;
+}

package/dist/interfaces/error-response.interface.js

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

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

@@ -0,0 +1,20 @@
+import type { Context } from 'hono';
+import type { Constructor } from '../types';
+/**
+ * Interface for exception filters
+ * Filters handle and transform exceptions thrown during request processing
+ */
+export interface IFilter {
+    /**
+     * Method to catch and handle exceptions
+     * @param exception - The exception that was thrown
+     * @param context - The Hono context object
+     * @returns A Response object or undefined if the exception should be passed to the next filter
+     */
+    catch(exception: Error, context: Context): Promise<Response | undefined> | Response | undefined;
+}
+/**
+ * Type for exception filters
+ * Can be either a class implementing IFilter or an instance of IFilter
+ */
+export type FilterType = Constructor<IFilter> | IFilter;

package/dist/interfaces/filter.interface.js

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

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

@@ -0,0 +1,21 @@
+import type { Constructor } from '../types';
+import type { Context } from 'hono';
+/**
+ * Interface defining a guard.
+ * Guards determine whether a request should be handled by the route handler or not.
+ */
+export interface IGuard {
+    /**
+     * Method to implement the guard logic.
+     * Return true to allow the request to proceed, false to deny.
+     *
+     * @param context - The Hono context object
+     * @returns A boolean or Promise<boolean> indicating if the request is allowed
+     */
+    canActivate(context: Context): boolean | Promise<boolean>;
+}
+/**
+ * Type for guard classes
+ * Can be either a constructor of IGuard or an instance of IGuard
+ */
+export type GuardType = Constructor<IGuard> | IGuard;

package/dist/interfaces/guard.interface.js

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

package/dist/interfaces/handler-invocation.interface.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from 'hono';
+/**
+ * Input contract for invoking route handlers and mapping results to HTTP responses.
+ */
+export interface HandlerInvocationInput {
+    handler: (...args: unknown[]) => Promise<unknown> | unknown;
+    args: unknown[];
+    context: Context;
+    contextIndex?: number;
+}

package/dist/interfaces/handler-invocation.interface.js

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

package/dist/interfaces/honest-options.interface.d.ts

@@ -0,0 +1,121 @@
+import type { Context } from 'hono';
+import type { VERSION_NEUTRAL } from '../constants';
+import type { FilterType, GuardType, ILogger, MiddlewareType, PipeType, PluginEntry } from '../interfaces';
+import type { DiContainer } from './di-container.interface';
+/**
+ * Options for configuring the Honest application
+ */
+export interface HonestOptions {
+    /**
+     * Emit actionable startup guidance when initialization fails.
+     * - `true` enables concise hints
+     * - object form enables verbose hints with additional context
+     */
+    startupGuide?: boolean | {
+        verbose?: boolean;
+    };
+    /**
+     * Enable debug logging for startup diagnostics.
+     * - `true` enables all debug logs
+     * - object form enables specific categories
+     */
+    debug?: boolean | {
+        routes?: boolean;
+        plugins?: boolean;
+        pipeline?: boolean;
+        di?: boolean;
+        startup?: boolean;
+    };
+    /**
+     * Optional logger for structured framework events.
+     */
+    logger?: ILogger;
+    /**
+     * Optional strict-mode checks for startup validation.
+     */
+    strict?: {
+        /**
+         * When enabled, startup fails if no routes were registered.
+         */
+        requireRoutes?: boolean;
+    };
+    /**
+     * Optional warnings for unstable/deprecated behavior.
+     */
+    deprecations?: {
+        /**
+         * Print pre-v1 instability warning during startup.
+         */
+        printPreV1Warning?: boolean;
+    };
+    /**
+     * Container instance for dependency injection
+     */
+    container?: DiContainer;
+    /**
+     * Hono-specific options
+     */
+    hono?: {
+        /**
+         * Whether to use strict matching for routes
+         */
+        strict?: boolean;
+        /**
+         * Custom router to use
+         */
+        router?: any;
+        /**
+         * Function to extract path from request
+         */
+        getPath?: (request: Request, options?: any) => string;
+    };
+    /**
+     * Global routing options
+     */
+    routing?: {
+        /**
+         * Global API prefix to apply to all routes (e.g. /api)
+         */
+        prefix?: string;
+        /**
+         * Global API version to apply to all routes (e.g. 1 becomes /v1)
+         * Set to VERSION_NEUTRAL to make routes accessible both with and without version prefix
+         * Set to an array of numbers to make routes available at multiple versions
+         */
+        version?: number | typeof VERSION_NEUTRAL | number[];
+    };
+    /**
+     * Global components to apply to all routes
+     */
+    components?: {
+        /**
+         * Global middleware to apply to all routes
+         */
+        middleware?: MiddlewareType[];
+        /**
+         * Global guards to apply to all routes
+         */
+        guards?: GuardType[];
+        /**
+         * Global pipes to apply to all routes
+         */
+        pipes?: PipeType[];
+        /**
+         * Global exception filters to apply to all routes
+         */
+        filters?: FilterType[];
+    };
+    /**
+     * Plugins for extending the application functionality.
+     * Each entry can be a plain plugin or an object with plugin and optional pre/post processors.
+     */
+    plugins?: PluginEntry[];
+    /**
+     * Default exception handler to use when no filter matches
+     */
+    onError?: (error: unknown, context: Context) => Response | Promise<Response>;
+    /**
+     * Default not found handler for routes that don't match any pattern
+     */
+    notFound?: (context: Context) => Response | Promise<Response>;
+}

package/dist/interfaces/honest-options.interface.js

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

package/dist/interfaces/http-method-options.interface.d.ts

@@ -0,0 +1,38 @@
+import type { VERSION_NEUTRAL } from '../constants';
+/**
+ * Options for HTTP method decorators (@Get, @Post, @Put, @Delete, etc.)
+ *
+ * @example
+ * ```typescript
+ * @Get('users', { prefix: 'api', version: 2 })
+ * getUsers() {
+ *   // ...
+ * }
+ * ```
+ */
+export interface HttpMethodOptions {
+    /**
+     * Optional prefix for this specific route, overrides controller and global prefix.
+     * Set to null to explicitly remove any prefix for this route.
+     *
+     * @example
+     * ```typescript
+     * @Get('users', { prefix: 'api' })     // -> /api/users
+     * @Get('users', { prefix: null })      // -> /users (no prefix)
+     * @Get('users', { prefix: 'v2/api' })  // -> /v2/api/users
+     * ```
+     */
+    prefix?: string | null;
+    /**
+     * API version for this specific route, overrides controller and global version.
+     *
+     * @example
+     * ```typescript
+     * @Get('users', { version: 1 })           // -> /v1/users
+     * @Get('users', { version: null })        // -> /users (no version)
+     * @Get('users', { version: VERSION_NEUTRAL }) // -> Both /users and /v1/users
+     * @Get('users', { version: [1, 2] })     // -> Both /v1/users and /v2/users
+     * ```
+     */
+    version?: number | null | typeof VERSION_NEUTRAL | number[];
+}

package/dist/interfaces/http-method-options.interface.js

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

package/dist/interfaces/index.d.ts

@@ -0,0 +1,21 @@
+export * from './application-context.interface';
+export * from './controller-options.interface';
+export * from './di-container.interface';
+export * from './logger.interface';
+export * from './error-response.interface';
+export * from './filter.interface';
+export * from './guard.interface';
+export * from './handler-invocation.interface';
+export * from './honest-options.interface';
+export * from './http-method-options.interface';
+export * from './metadata-repository.interface';
+export * from './middleware.interface';
+export * from './module-options.interface';
+export * from './parameter-metadata.interface';
+export * from './parameter-resolution.interface';
+export * from './pipeline-context.interface';
+export * from './pipe.interface';
+export * from './plugin.interface';
+export * from './route-definition.interface';
+export * from './route-info.interface';
+export * from './service-registry.interface';

package/dist/interfaces/index.js

@@ -0,0 +1,21 @@
+export * from './application-context.interface';
+export * from './controller-options.interface';
+export * from './di-container.interface';
+export * from './logger.interface';
+export * from './error-response.interface';
+export * from './filter.interface';
+export * from './guard.interface';
+export * from './handler-invocation.interface';
+export * from './honest-options.interface';
+export * from './http-method-options.interface';
+export * from './metadata-repository.interface';
+export * from './middleware.interface';
+export * from './module-options.interface';
+export * from './parameter-metadata.interface';
+export * from './parameter-resolution.interface';
+export * from './pipeline-context.interface';
+export * from './pipe.interface';
+export * from './plugin.interface';
+export * from './route-definition.interface';
+export * from './route-info.interface';
+export * from './service-registry.interface';

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

@@ -0,0 +1,23 @@
+/**
+ * Log level.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Log category used to filter or route events.
+ */
+export type LogCategory = 'startup' | 'routes' | 'plugins' | 'deprecations' | 'pipeline' | 'di' | 'errors';
+/**
+ * Structured log event emitted by Honest runtime components.
+ */
+export interface LogEvent {
+    level: LogLevel;
+    category: LogCategory;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Logger contract.
+ */
+export interface ILogger {
+    emit(event: LogEvent): void;
+}

package/dist/interfaces/logger.interface.js

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

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

@@ -0,0 +1,30 @@
+import type { ControllerOptions } from './controller-options.interface';
+import type { FilterType } from './filter.interface';
+import type { GuardType } from './guard.interface';
+import type { MiddlewareType } from './middleware.interface';
+import type { ModuleOptions } from './module-options.interface';
+import type { ParameterMetadata } from './parameter-metadata.interface';
+import type { PipeType } from './pipe.interface';
+import type { RouteDefinition } from './route-definition.interface';
+import type { Constructor } from '../types';
+export type MetadataComponentType = 'middleware' | 'guard' | 'pipe' | 'filter';
+export interface MetadataComponentTypeMap {
+    middleware: MiddlewareType;
+    guard: GuardType;
+    pipe: PipeType;
+    filter: FilterType;
+}
+/**
+ * Runtime metadata access contract used by framework managers.
+ */
+export interface IMetadataRepository {
+    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][];
+}

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

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

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

@@ -0,0 +1,22 @@
+import type { Context, Next } from 'hono';
+import type { Constructor } from '../types';
+/**
+ * Interface for HTTP middleware components
+ * Middleware can process requests before they reach the route handler
+ * and modify both the request and response
+ */
+export interface IMiddleware {
+    /**
+     * Processes an HTTP request/response
+     * @param c - The Hono context containing request and response information
+     * @param next - Function to call the next middleware in the chain
+     * @returns A Promise that resolves to a Response or void
+     * @throws {Error} If middleware processing fails
+     */
+    use(c: Context, next: Next): Promise<Response | void>;
+}
+/**
+ * Type for middleware implementations
+ * Can be either a class implementing IMiddleware or an instance of IMiddleware
+ */
+export type MiddlewareType = Constructor<IMiddleware> | IMiddleware;

package/dist/interfaces/middleware.interface.js

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

package/dist/interfaces/module-options.interface.d.ts

@@ -0,0 +1,18 @@
+import type { Constructor } from '../types';
+/**
+ * Options for configuring a module
+ */
+export interface ModuleOptions {
+    /**
+     * List of controller classes
+     */
+    controllers?: Constructor[];
+    /**
+     * List of service classes
+     */
+    services?: Constructor[];
+    /**
+     * List of imported modules
+     */
+    imports?: Constructor[];
+}

package/dist/interfaces/module-options.interface.js

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