node-honest 0.0.1 → 0.1.0

package/dist/di/container.js

@@ -1,114 +0,0 @@
-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

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

package/dist/di/index.js

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

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

@@ -1,19 +0,0 @@
-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

@@ -1,23 +0,0 @@
-/**
- * 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

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

package/dist/errors/index.js

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

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

@@ -1,28 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

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

package/dist/handlers/index.js

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

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

@@ -1,14 +0,0 @@
-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

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1,25 +0,0 @@
-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

@@ -1,90 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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;

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

@@ -1,30 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,60 +0,0 @@
-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

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

package/dist/helpers/index.js

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

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

@@ -1,35 +0,0 @@
-/**
- * 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

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

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

@@ -1,17 +0,0 @@
-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

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

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

@@ -1,35 +0,0 @@
-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

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

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

@@ -1,13 +0,0 @@
-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

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

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

@@ -1,20 +0,0 @@
-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

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