honest-node 1.0.0

package/dist/decorators/parameter.decorator.js

@@ -0,0 +1,59 @@
+import { HONEST_PIPELINE_BODY_CACHE_KEY } from '../constants';
+import { createParamDecorator } from '../helpers';
+/**
+ * Decorator that binds the request body to a parameter
+ * @param data - Optional property name to extract from the body
+ */
+export const Body = createParamDecorator('body', async (data, ctx) => {
+    let body = ctx.get(HONEST_PIPELINE_BODY_CACHE_KEY);
+    if (body === undefined) {
+        body = await ctx.req.json();
+        ctx.set(HONEST_PIPELINE_BODY_CACHE_KEY, body);
+    }
+    if (data && body && typeof body === 'object') {
+        return body[String(data)];
+    }
+    return body;
+});
+/**
+ * Decorator that binds a route parameter to a parameter
+ * @param data - The parameter name in the route
+ */
+export const Param = createParamDecorator('param', (data, ctx) => {
+    return data ? ctx.req.param(String(data)) : ctx.req.param();
+});
+/**
+ * Decorator that binds a query parameter to a parameter
+ * @param data - The query parameter name
+ */
+export const Query = createParamDecorator('query', (data, ctx) => {
+    return data ? ctx.req.query(String(data)) : ctx.req.query();
+});
+/**
+ * Decorator that binds a header value to a parameter
+ * @param data - The header name
+ */
+export const Header = createParamDecorator('header', (data, ctx) => {
+    return data ? ctx.req.header(String(data)) : ctx.req.header();
+});
+/**
+ * Decorator that binds the request object to a parameter
+ */
+export const Req = createParamDecorator('request', (_, ctx) => ctx.req);
+export const Request = createParamDecorator('request', (_, ctx) => ctx.req);
+/**
+ * Decorator that binds the response object to a parameter
+ */
+export const Res = createParamDecorator('response', (_, ctx) => ctx.res);
+export const Response = createParamDecorator('response', (_, ctx) => ctx.res);
+/**
+ * Decorator that binds the context object to a parameter
+ */
+export const Ctx = createParamDecorator('context', (_, ctx) => ctx);
+export const Context = createParamDecorator('context', (_, ctx) => ctx);
+/**
+ * Decorator that binds a context variable to a parameter
+ * @param data - The variable name to retrieve from context
+ */
+export const Var = createParamDecorator('variable', (data, ctx) => data === undefined ? undefined : ctx.get(String(data)));
+export const Variable = createParamDecorator('variable', (data, ctx) => data === undefined ? undefined : ctx.get(String(data)));

package/dist/decorators/service.decorator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Decorator that marks a class as a service
+ * Services are singleton classes that can be injected as dependencies
+ * @returns A class decorator function
+ */
+export declare function Service(): ClassDecorator;

package/dist/decorators/service.decorator.js

@@ -0,0 +1,11 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Decorator that marks a class as a service
+ * Services are singleton classes that can be injected as dependencies
+ * @returns A class decorator function
+ */
+export function Service() {
+    return (target) => {
+        MetadataRegistry.addService(target);
+    };
+}

package/dist/decorators/use-component.decorator.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentType, ComponentTypeMap } from '../registries';
+import type { Constructor } from '../types';
+/**
+ * Generic decorator that applies components of a specific type to a controller class or method
+ * @template T - The type of component being applied
+ * @param type - The component type identifier
+ * @param components - Array of components to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export declare function UseComponent<T extends ComponentType>(type: T, ...components: ComponentTypeMap[T][]): (target: Constructor | object, propertyKey?: string | symbol) => void;

package/dist/decorators/use-component.decorator.js

@@ -0,0 +1,19 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Generic decorator that applies components of a specific type to a controller class or method
+ * @template T - The type of component being applied
+ * @param type - The component type identifier
+ * @param components - Array of components to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export function UseComponent(type, ...components) {
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            const controllerClass = target.constructor;
+            components.forEach((component) => MetadataRegistry.registerHandler(type, controllerClass, propertyKey, component));
+        }
+        else {
+            components.forEach((component) => MetadataRegistry.registerController(type, target, component));
+        }
+    };
+}

package/dist/decorators/use-filters.decorator.d.ts

@@ -0,0 +1,8 @@
+import type { FilterType } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Decorator that applies exception filters to a controller class or method
+ * @param filters - Array of exception filters to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export declare function UseFilters(...filters: FilterType[]): (target: Constructor | object, propertyKey?: string | symbol) => void;

package/dist/decorators/use-filters.decorator.js

@@ -0,0 +1,17 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Decorator that applies exception filters to a controller class or method
+ * @param filters - Array of exception filters to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export function UseFilters(...filters) {
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            const controllerClass = target.constructor;
+            filters.forEach((filter) => MetadataRegistry.registerHandler('filter', controllerClass, propertyKey, filter));
+        }
+        else {
+            filters.forEach((filter) => MetadataRegistry.registerController('filter', target, filter));
+        }
+    };
+}

package/dist/decorators/use-guards.decorator.d.ts

@@ -0,0 +1,9 @@
+import type { GuardType } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Decorator that applies guards to a controller class or method
+ * Guards determine whether a request should be handled by the route handler
+ * @param guards - Array of guards to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export declare function UseGuards(...guards: GuardType[]): (target: Constructor | object, propertyKey?: string | symbol) => void;

package/dist/decorators/use-guards.decorator.js

@@ -0,0 +1,18 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Decorator that applies guards to a controller class or method
+ * Guards determine whether a request should be handled by the route handler
+ * @param guards - Array of guards to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export function UseGuards(...guards) {
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            const controllerClass = target.constructor;
+            guards.forEach((guard) => MetadataRegistry.registerHandler('guard', controllerClass, propertyKey, guard));
+        }
+        else {
+            guards.forEach((guard) => MetadataRegistry.registerController('guard', target, guard));
+        }
+    };
+}

package/dist/decorators/use-middleware.decorator.d.ts

@@ -0,0 +1,9 @@
+import type { MiddlewareType } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Decorator that applies middleware to a controller class or method
+ * Middleware functions run before the route handler and can modify the request/response
+ * @param middleware - Array of middleware functions to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export declare function UseMiddleware(...middleware: MiddlewareType[]): (target: Constructor | object, propertyKey?: string | symbol) => void;

package/dist/decorators/use-middleware.decorator.js

@@ -0,0 +1,18 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Decorator that applies middleware to a controller class or method
+ * Middleware functions run before the route handler and can modify the request/response
+ * @param middleware - Array of middleware functions to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export function UseMiddleware(...middleware) {
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            const controllerClass = target.constructor;
+            middleware.forEach((mw) => MetadataRegistry.registerHandler('middleware', controllerClass, propertyKey, mw));
+        }
+        else {
+            middleware.forEach((mw) => MetadataRegistry.registerController('middleware', target, mw));
+        }
+    };
+}

package/dist/decorators/use-pipes.decorator.d.ts

@@ -0,0 +1,9 @@
+import type { PipeType } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Decorator that applies transformation pipes to a controller class or method
+ * Pipes transform input data before it reaches the route handler
+ * @param pipes - Array of pipes to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export declare function UsePipes(...pipes: PipeType[]): (target: Constructor | object, propertyKey?: string | symbol) => void;

package/dist/decorators/use-pipes.decorator.js

@@ -0,0 +1,18 @@
+import { MetadataRegistry } from '../registries';
+/**
+ * Decorator that applies transformation pipes to a controller class or method
+ * Pipes transform input data before it reaches the route handler
+ * @param pipes - Array of pipes to apply
+ * @returns A decorator function that can be used at class or method level
+ */
+export function UsePipes(...pipes) {
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            const controllerClass = target.constructor;
+            pipes.forEach((pipe) => MetadataRegistry.registerHandler('pipe', controllerClass, propertyKey, pipe));
+        }
+        else {
+            pipes.forEach((pipe) => MetadataRegistry.registerController('pipe', target, pipe));
+        }
+    };
+}

package/dist/di/container.d.ts

@@ -0,0 +1,34 @@
+import type { DiContainer, ILogger, IServiceRegistry } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Dependency Injection container that manages class instances and their dependencies
+ */
+export declare class Container implements DiContainer {
+    private readonly serviceRegistry;
+    private readonly logger;
+    private readonly debugDi;
+    constructor(serviceRegistry?: IServiceRegistry, logger?: ILogger, debugDi?: boolean);
+    /**
+     * Map of class constructors to their instances
+     */
+    private instances;
+    private emitLog;
+    /**
+     * Resolves a class instance, creating it if necessary and injecting its dependencies
+     * @param target - The class constructor to resolve
+     * @returns An instance of the target class
+     */
+    resolve<T>(target: Constructor<T>): T;
+    /**
+     * Internal recursive resolver with circular dependency tracking
+     */
+    private resolveWithTracking;
+    /**
+     * Registers a pre-created instance for a class
+     * @param target - The class constructor to register
+     * @param instance - The instance to register
+     */
+    register<T>(target: Constructor<T>, instance: T): void;
+    has<T>(target: Constructor<T>): boolean;
+    clear(): void;
+}

package/dist/di/container.js

@@ -0,0 +1,114 @@
+import { NoopLogger } from '../loggers';
+import { StaticServiceRegistry } from '../registries';
+/**
+ * Dependency Injection container that manages class instances and their dependencies
+ */
+export class Container {
+    serviceRegistry;
+    logger;
+    debugDi;
+    constructor(serviceRegistry = new StaticServiceRegistry(), logger = new NoopLogger(), debugDi = false) {
+        this.serviceRegistry = serviceRegistry;
+        this.logger = logger;
+        this.debugDi = debugDi;
+    }
+    /**
+     * Map of class constructors to their instances
+     */
+    instances = new Map();
+    emitLog(event) {
+        if (!this.debugDi) {
+            return;
+        }
+        this.logger.emit(event);
+    }
+    /**
+     * Resolves a class instance, creating it if necessary and injecting its dependencies
+     * @param target - The class constructor to resolve
+     * @returns An instance of the target class
+     */
+    resolve(target) {
+        return this.resolveWithTracking(target, new Set());
+    }
+    /**
+     * Internal recursive resolver with circular dependency tracking
+     */
+    resolveWithTracking(target, resolving) {
+        if (this.instances.has(target)) {
+            this.emitLog({
+                level: 'debug',
+                category: 'di',
+                message: `Resolved ${target.name} from DI cache`
+            });
+            return this.instances.get(target);
+        }
+        if (resolving.has(target)) {
+            const cycle = [...resolving.keys(), target].map((t) => t.name).join(' -> ');
+            this.emitLog({
+                level: 'error',
+                category: 'di',
+                message: `Circular dependency detected while resolving ${target.name}`,
+                details: { cycle }
+            });
+            throw new Error(`Circular dependency detected: ${cycle}`);
+        }
+        resolving.add(target);
+        this.emitLog({
+            level: 'debug',
+            category: 'di',
+            message: `Resolving ${target.name}`,
+            details: { resolving: [...resolving].map((constructor) => constructor.name) }
+        });
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target) || [];
+        if (target.length > 0 && paramTypes.length === 0) {
+            if (!this.serviceRegistry.isService(target)) {
+                this.emitLog({
+                    level: 'error',
+                    category: 'di',
+                    message: `Cannot resolve ${target.name}: missing @Service() decorator`
+                });
+                throw new Error(`Cannot resolve ${target.name}: it is not decorated with @Service(). Did you forget to add @Service() to the class?`);
+            }
+            this.emitLog({
+                level: 'error',
+                category: 'di',
+                message: `Cannot resolve ${target.name}: missing constructor metadata`
+            });
+            throw new Error(`Cannot resolve dependencies for ${target.name}: constructor metadata is missing. Ensure 'reflect-metadata' is imported and 'emitDecoratorMetadata' is enabled.`);
+        }
+        const dependencies = paramTypes.map((paramType, index) => {
+            if (!paramType || paramType === Object || paramType === Array || paramType === Function) {
+                this.emitLog({
+                    level: 'error',
+                    category: 'di',
+                    message: `Cannot resolve dependency at index ${index} of ${target.name}`
+                });
+                throw new Error(`Cannot resolve dependency at index ${index} of ${target.name}. Use concrete class types for constructor dependencies.`);
+            }
+            return this.resolveWithTracking(paramType, new Set(resolving));
+        });
+        const instance = new target(...dependencies);
+        this.instances.set(target, instance);
+        this.emitLog({
+            level: 'debug',
+            category: 'di',
+            message: `Created ${target.name} instance`,
+            details: { dependencyCount: dependencies.length }
+        });
+        return instance;
+    }
+    /**
+     * Registers a pre-created instance for a class
+     * @param target - The class constructor to register
+     * @param instance - The instance to register
+     */
+    register(target, instance) {
+        this.instances.set(target, instance);
+    }
+    has(target) {
+        return this.instances.has(target);
+    }
+    clear() {
+        this.instances.clear();
+    }
+}

package/dist/di/index.d.ts

@@ -0,0 +1 @@
+export * from './container';

package/dist/di/index.js

@@ -0,0 +1 @@
+export * from './container';

package/dist/errors/framework.error.d.ts

@@ -0,0 +1,19 @@
+export interface FrameworkErrorOptions {
+    status?: number;
+    code: string;
+    category: string;
+    remediation?: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/**
+ * Structured framework-level error with machine-readable metadata.
+ */
+export declare class FrameworkError extends Error {
+    readonly status?: number;
+    readonly code: string;
+    readonly category: string;
+    readonly remediation?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options: FrameworkErrorOptions);
+}

package/dist/errors/framework.error.js

@@ -0,0 +1,23 @@
+/**
+ * Structured framework-level error with machine-readable metadata.
+ */
+export class FrameworkError extends Error {
+    status;
+    code;
+    category;
+    remediation;
+    details;
+    constructor(message, options) {
+        super(message);
+        this.name = 'FrameworkError';
+        this.status = options.status;
+        this.code = options.code;
+        this.category = options.category;
+        this.remediation = options.remediation;
+        this.details = options.details;
+        if (options.cause !== undefined) {
+            ;
+            this.cause = options.cause;
+        }
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './framework.error';

package/dist/errors/index.js

@@ -0,0 +1 @@
+export * from './framework.error';

package/dist/handlers/error.handler.d.ts

@@ -0,0 +1,28 @@
+import type { Context } from 'hono';
+/**
+ * Handler for managing application-wide error responses
+ * Provides a consistent way to handle and format error responses across the application
+ */
+export declare class ErrorHandler {
+    /**
+     * Creates a middleware function that handles error responses
+     * @returns A middleware function that formats and returns error responses using createErrorResponse
+     */
+    static handle(): (err: unknown, c: Context) => Promise<Response & import("hono").TypedResponse<{
+        status: number;
+        message: string;
+        timestamp: string;
+        path: string;
+        requestId?: string | undefined;
+        code?: string | undefined;
+        details?: {
+            [x: string]: any;
+        } | undefined;
+        errors?: {
+            property: string;
+            constraints: {
+                [x: string]: string;
+            };
+        }[] | undefined;
+    }, -1 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "json">>;
+}

package/dist/handlers/error.handler.js

@@ -0,0 +1,17 @@
+import { createErrorResponse } from '../helpers';
+/**
+ * Handler for managing application-wide error responses
+ * Provides a consistent way to handle and format error responses across the application
+ */
+export class ErrorHandler {
+    /**
+     * Creates a middleware function that handles error responses
+     * @returns A middleware function that formats and returns error responses using createErrorResponse
+     */
+    static handle() {
+        return async (err, c) => {
+            const { response, status } = createErrorResponse(err, c);
+            return c.json(response, status);
+        };
+    }
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './error.handler';
+export * from './not-found.handler';

package/dist/handlers/index.js

@@ -0,0 +1,2 @@
+export * from './error.handler';
+export * from './not-found.handler';

package/dist/handlers/not-found.handler.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from 'hono';
+/**
+ * Handler for managing 404 Not Found responses
+ * Provides a consistent way to handle requests to non-existent routes
+ */
+export declare class NotFoundHandler {
+    /**
+     * Creates a middleware function that handles 404 Not Found responses
+     * @returns A middleware function that returns a JSON response with a 404 status
+     */
+    static handle(): (c: Context) => Promise<Response & import("hono").TypedResponse<{
+        message: string;
+    }, 404, "json">>;
+}

package/dist/handlers/not-found.handler.js

@@ -0,0 +1,17 @@
+/**
+ * Handler for managing 404 Not Found responses
+ * Provides a consistent way to handle requests to non-existent routes
+ */
+export class NotFoundHandler {
+    /**
+     * Creates a middleware function that handles 404 Not Found responses
+     * @returns A middleware function that returns a JSON response with a 404 status
+     */
+    static handle() {
+        return async (c) => {
+            return c.json({
+                message: `Not Found - ${c.req.path}`
+            }, 404);
+        };
+    }
+}

package/dist/helpers/create-error-response.helper.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import type { ErrorResponse } from '../interfaces';
+/**
+ * Creates a standardized error response object
+ * @param exception - The error or exception object to process
+ * @param context - The Hono context object containing request information
+ * @param options - Optional configuration for the error response
+ * @param options.status - HTTP status code to override the default
+ * @param options.title - Custom error message to override the default
+ * @param options.detail - Additional error details
+ * @param options.code - Custom error code
+ * @param options.additionalDetails - Extra information to include in the response
+ * @returns Object containing the formatted error response and HTTP status code
+ */
+export declare function createErrorResponse(exception: unknown, context: Context, options?: {
+    status?: number;
+    title?: string;
+    detail?: string;
+    code?: string;
+    additionalDetails?: Record<string, unknown>;
+}): {
+    response: ErrorResponse;
+    status: ContentfulStatusCode;
+};

package/dist/helpers/create-error-response.helper.js

@@ -0,0 +1,90 @@
+import { HTTPException } from 'hono/http-exception';
+import { FrameworkError } from '../errors';
+/**
+ * Creates a standardized error response object
+ * @param exception - The error or exception object to process
+ * @param context - The Hono context object containing request information
+ * @param options - Optional configuration for the error response
+ * @param options.status - HTTP status code to override the default
+ * @param options.title - Custom error message to override the default
+ * @param options.detail - Additional error details
+ * @param options.code - Custom error code
+ * @param options.additionalDetails - Extra information to include in the response
+ * @returns Object containing the formatted error response and HTTP status code
+ */
+export function createErrorResponse(exception, context, options) {
+    const normalizedException = exception instanceof Error ? exception : new Error(String(exception));
+    const timestamp = new Date().toISOString();
+    const requestId = context.get('requestId');
+    const path = context.req.path;
+    // Handle HTTPException (Hono's built-in exception)
+    if (normalizedException instanceof HTTPException) {
+        const response = {
+            status: options?.status || normalizedException.status,
+            message: options?.title || normalizedException.message,
+            timestamp,
+            path,
+            requestId,
+            code: options?.code,
+            details: options?.additionalDetails,
+            ...(options?.detail && { detail: options.detail })
+        };
+        return { response, status: (options?.status || normalizedException.status) };
+    }
+    if (normalizedException instanceof FrameworkError) {
+        const status = (options?.status || normalizedException.status || 500);
+        const response = {
+            status,
+            message: options?.title || normalizedException.message,
+            timestamp,
+            path,
+            requestId,
+            code: options?.code || normalizedException.code,
+            details: {
+                category: normalizedException.category,
+                remediation: normalizedException.remediation,
+                ...normalizedException.details,
+                ...options?.additionalDetails
+            },
+            ...(options?.detail && { detail: options.detail })
+        };
+        return { response, status };
+    }
+    // Combined status handling
+    if (normalizedException.statusCode ||
+        normalizedException.status) {
+        const defaultStatus = normalizedException.statusCode ||
+            normalizedException.status ||
+            500;
+        const status = options?.status || defaultStatus;
+        const response = {
+            status,
+            message: options?.title || normalizedException.message,
+            timestamp,
+            path,
+            requestId,
+            code: options?.code || normalizedException.name,
+            details: options?.additionalDetails,
+            ...(options?.detail && { detail: options.detail })
+        };
+        return {
+            response,
+            status: status
+        };
+    }
+    // Handle unexpected errors
+    const status = (options?.status || 500);
+    const response = {
+        status,
+        message: options?.title ||
+            (process.env.NODE_ENV === 'production' ? 'Internal Server Error' : normalizedException.message),
+        timestamp,
+        path,
+        requestId,
+        code: options?.code || normalizedException.name,
+        details: options?.additionalDetails ||
+            (process.env.NODE_ENV === 'development' ? { stack: normalizedException.stack } : undefined),
+        ...(options?.detail && { detail: options.detail })
+    };
+    return { response, status };
+}

package/dist/helpers/create-http-method-decorator.helper.d.ts

@@ -0,0 +1,16 @@
+import type { HttpMethodOptions } from '../interfaces';
+/**
+ * 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 declare function createHttpMethodDecorator(method: string): (path?: string, options?: HttpMethodOptions) => MethodDecorator;