honestjs 0.1.0

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

@@ -0,0 +1,109 @@
+import type { Hono } from 'hono';
+import { VERSION_NEUTRAL } from '../constants';
+import type { DiContainer } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Manager class for handling route registration in the Honest framework
+ * Responsible for:
+ * - Registering controller routes with the Hono application
+ * - Managing route versioning and prefixing
+ * - Applying middleware and guards to routes
+ * - Handling parameter transformation and validation
+ *
+ * Versioning features:
+ * - Global version setting can be overridden at controller or method level
+ * - Controllers can opt out of versioning by setting version to null
+ * - Routes can use VERSION_NEUTRAL to be accessible with and without version prefix
+ * - Routes can specify an array of versions to support multiple versions
+ *
+ * Path handling:
+ * - Global prefix can be overridden at controller level
+ * - Paths are automatically normalized
+ * - Final path structure: prefix/version/controller-path/method-path
+ */
+export declare class RouteManager {
+    private hono;
+    private container;
+    private globalPrefix?;
+    private globalVersion?;
+    /**
+     * Creates a new RouteManager instance
+     * @param hono - The Hono application instance for route registration
+     * @param container - The dependency injection container for resolving controllers and dependencies
+     * @param options - Configuration options for the route manager
+     * @param options.prefix - Optional global prefix for all routes
+     * @param options.version - Optional global version or version array for all routes
+     */
+    constructor(hono: Hono, container: DiContainer, options?: {
+        prefix?: string;
+        version?: number | typeof VERSION_NEUTRAL | number[];
+    });
+    /**
+     * Applies global middleware to the application
+     */
+    private applyGlobalMiddleware;
+    /**
+     * Normalizes a path segment for route registration
+     * @param path - The path segment to normalize
+     * @returns The normalized path segment
+     */
+    private normalizePath;
+    /**
+     * Registers a wrapper handler with middleware for a route
+     * @param method - HTTP method
+     * @param path - Full path for the route
+     * @param handlerMiddleware - Middleware for the handler
+     * @param wrapperHandler - The wrapper handler function
+     */
+    private registerRouteHandler;
+    /**
+     * Builds a route path with the correct order: prefix, version, controller path, method path
+     * @param prefix - Global or controller-specific prefix
+     * @param version - Version string (e.g., '/v1') or empty string if no version
+     * @param controllerPath - Controller path
+     * @param methodPath - Method-specific path
+     * @returns Properly formatted full path
+     */
+    private buildRoutePath;
+    /**
+     * Formats a version number or VERSION_NEUTRAL into a path segment
+     * @param version - Version number or VERSION_NEUTRAL
+     * @returns Formatted version string (e.g., '/v1') or empty string if null
+     */
+    private formatVersionSegment;
+    /**
+     * Registers a controller and all its routes with the application
+     * Handles versioning, prefixing, and middleware application
+     *
+     * @param controllerClass - The controller class to register
+     * @throws {Error} If controller registration fails or if required dependencies cannot be resolved
+     *
+     * Route registration process:
+     * 1. Resolves controller instance and metadata
+     * 2. Processes controller-level options (prefix, version)
+     * 3. Registers each route with appropriate:
+     *    - Path construction (prefix/version/controller-path/method-path)
+     *    - Middleware application
+     *    - Parameter processing
+     *    - Guard validation
+     */
+    registerController(controllerClass: Constructor): Promise<void>;
+    /**
+     * Registers a specific route with the application
+     * Handles middleware setup, parameter processing, and response handling
+     *
+     * @param controllerInstance - Instance of the controller containing the route handler
+     * @param route - Route metadata including path and HTTP method
+     * @param parameterMetadata - Metadata for parameter processing
+     * @param contextIndices - Map of context parameter indices
+     * @param controllerClass - The controller class
+     * @param prefix - Route prefix
+     * @param versionSegment - Version segment of the path
+     * @param controllerSegment - Controller path segment
+     * @param methodSegment - Method-specific path segment
+     * @param method - HTTP method for the route
+     *
+     * @throws {Error} If route registration fails
+     */
+    private registerRoute;
+}

package/dist/registries/index.d.ts

@@ -0,0 +1,2 @@
+export * from './metadata.registry';
+export * from './route.registry';

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

@@ -0,0 +1,172 @@
+import type { ControllerOptions, FilterType, GuardType, MiddlewareType, ModuleOptions, ParameterMetadata, PipeType, RouteDefinition } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Available component types that can be registered at different levels in the application
+ * Each type corresponds to a specific aspect of request processing
+ */
+export type ComponentType = 'middleware' | 'guard' | 'pipe' | 'filter';
+/**
+ * Union type of all possible component instances
+ * Represents any type of component that can be registered in the application
+ */
+export type ComponentInstance = MiddlewareType | GuardType | PipeType | FilterType;
+/**
+ * Maps component type identifiers to their specific instance types
+ * Used for type-safe component registration and retrieval
+ */
+export interface ComponentTypeMap {
+    middleware: MiddlewareType;
+    guard: GuardType;
+    pipe: PipeType;
+    filter: FilterType;
+}
+/**
+ * Central registry for managing application metadata
+ * Stores and provides access to:
+ * - Route definitions and controller configurations
+ * - Service and module registrations
+ * - Parameter metadata and context indices
+ * - Component registrations at global, controller, and handler levels
+ */
+export declare class MetadataRegistry {
+    /**
+     * Stores route definitions for each controller
+     * Maps controller classes to their route configurations
+     */
+    private static readonly routes;
+    /**
+     * Stores base paths for controllers
+     * Maps controller classes to their route prefixes
+     */
+    private static readonly controllers;
+    /**
+     * Stores configuration options for controllers
+     * Includes settings like versioning and prefix options
+     */
+    private static readonly controllerOptions;
+    /**
+     * Registry of service classes
+     * Used for dependency injection and lifecycle management
+     */
+    private static readonly services;
+    /**
+     * Stores configuration options for modules
+     * Includes imports, exports, providers, and controllers
+     */
+    private static readonly modules;
+    /**
+     * Stores parameter metadata for controller methods
+     * Used for parameter transformation and validation
+     */
+    private static readonly parameters;
+    /**
+     * Stores indices of context parameters in controller methods
+     * Used for optimizing context injection
+     */
+    private static readonly contextIndices;
+    /**
+     * Registry for global-level components
+     * Components registered here apply to all routes
+     */
+    private static readonly global;
+    /**
+     * Registry for controller-level components
+     * Components registered here apply to all routes in a specific controller
+     */
+    private static readonly controller;
+    /**
+     * Registry for handler-level components
+     * Components registered here apply to specific route handlers
+     */
+    private static readonly handler;
+    /**
+     * Gets all route definitions for a controller
+     * @param controller - The controller class to get routes for
+     * @returns Array of route definitions for the controller
+     */
+    static getRoutes(controller: Constructor): RouteDefinition[];
+    /**
+     * Set routes for a controller
+     */
+    static setRoutes(controller: Constructor, routes: RouteDefinition[]): void;
+    /**
+     * Add a route to a controller
+     */
+    static addRoute(controller: Constructor, route: RouteDefinition): void;
+    /**
+     * Get controller path
+     */
+    static getControllerPath(controller: Constructor): string;
+    /**
+     * Set controller path
+     */
+    static setControllerPath(controller: Constructor, path: string): void;
+    /**
+     * Get controller options
+     */
+    static getControllerOptions(controller: Constructor): ControllerOptions;
+    /**
+     * Set controller options
+     */
+    static setControllerOptions(controller: Constructor, options: ControllerOptions): void;
+    /**
+     * Check if class is a service
+     */
+    static isService(service: Constructor): boolean;
+    /**
+     * Add a service
+     */
+    static addService(service: Constructor): void;
+    /**
+     * Get all services
+     */
+    static getAllServices(): Set<Constructor>;
+    /**
+     * Get module options
+     */
+    static getModuleOptions(module: Constructor): ModuleOptions | undefined;
+    /**
+     * Set module options
+     */
+    static setModuleOptions(module: Constructor, options: ModuleOptions): void;
+    /**
+     * Get parameter metadata
+     */
+    static getParameters(controller: Constructor): Map<string | symbol, ParameterMetadata[]>;
+    /**
+     * Set parameter metadata
+     */
+    static setParameterMap(controller: Constructor, params: Map<string | symbol, ParameterMetadata[]>): void;
+    /**
+     * Get context indices
+     */
+    static getContextIndices(controller: Constructor): Map<string | symbol, number>;
+    /**
+     * Set context indices
+     */
+    static setContextIndices(controller: Constructor, indices: Map<string | symbol, number>): void;
+    /**
+     * Register a component at the global level
+     */
+    static registerGlobal<T extends ComponentType>(type: T, component: ComponentTypeMap[T]): void;
+    /**
+     * Get all global components of a specific type
+     */
+    static getGlobal<T extends ComponentType>(type: T): Set<ComponentTypeMap[T]>;
+    /**
+     * Register a component at the controller level
+     */
+    static registerController<T extends ComponentType>(type: T, controller: Constructor, component: ComponentTypeMap[T]): void;
+    /**
+     * Get all controller-level components of a specific type for a controller
+     */
+    static getController<T extends ComponentType>(type: T, controller: Constructor): ComponentTypeMap[T][];
+    /**
+     * Register a component at the handler level
+     */
+    static registerHandler<T extends ComponentType>(type: T, handlerKey: string, component: ComponentTypeMap[T]): void;
+    /**
+     * Get all handler-level components of a specific type for a handler
+     */
+    static getHandler<T extends ComponentType>(type: T, handlerKey: string): ComponentTypeMap[T][];
+}

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

@@ -0,0 +1,63 @@
+import type { RouteInfo } from '../interfaces';
+/**
+ * Registry for managing and querying route information in the application
+ *
+ * Provides functionality to:
+ * - Register new routes with their metadata
+ * - Query routes by various criteria (controller, method, path)
+ * - Access route information for documentation and debugging
+ * - Manage route lifecycle (registration and cleanup)
+ *
+ * The registry maintains a read-only view of routes to prevent unintended modifications
+ */
+export declare class RouteRegistry {
+    /**
+     * Internal storage for registered routes
+     * Maintains the complete list of routes in registration order
+     */
+    private static readonly routes;
+    /**
+     * Registers a new route in the application
+     * @param routeInfo - Complete route information including path, method, and handler details
+     * @throws {Error} If the route information is invalid or incomplete
+     */
+    static registerRoute(routeInfo: RouteInfo): void;
+    /**
+     * Retrieves all registered routes in the application
+     * @returns A read-only array of all route information
+     * Routes are returned in their registration order
+     */
+    static getRoutes(): ReadonlyArray<RouteInfo>;
+    /**
+     * Retrieves all routes registered for a specific controller
+     * @param controllerName - Name or symbol identifying the controller
+     * @returns A read-only array of routes belonging to the specified controller
+     * Returns an empty array if no routes are found for the controller
+     */
+    static getRoutesByController(controllerName: string | symbol): ReadonlyArray<RouteInfo>;
+    /**
+     * Retrieves all routes registered for a specific HTTP method
+     * @param method - HTTP method to filter by (case-insensitive)
+     * @returns A read-only array of routes handling the specified HTTP method
+     * Returns an empty array if no routes are found for the method
+     */
+    static getRoutesByMethod(method: string): ReadonlyArray<RouteInfo>;
+    /**
+     * Retrieves routes matching a specific path pattern
+     * @param pattern - Regular expression to match against route paths
+     * @returns A read-only array of routes whose paths match the pattern
+     * Returns an empty array if no matching routes are found
+     * @example
+     * ```ts
+     * // Find all routes containing 'users'
+     * const userRoutes = RouteRegistry.getRoutesByPath(/users/);
+     * ```
+     */
+    static getRoutesByPath(pattern: RegExp): ReadonlyArray<RouteInfo>;
+    /**
+     * Removes all registered routes from the registry
+     * Primarily used for testing and development purposes
+     * Use with caution in production environments
+     */
+    static clear(): void;
+}

package/dist/types/constructor.type.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents a class constructor type
+ * Used throughout the framework for type-safe dependency injection and component registration
+ *
+ * @template T - The type of instance that the constructor creates
+ * @example
+ * ```ts
+ * class MyService {}
+ * const myConstructor: Constructor<MyService> = MyService;
+ * ```
+ */
+export type Constructor<T = any> = new (...args: any[]) => T;

package/dist/types/index.d.ts

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

package/dist/utils/common.util.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Type guard that checks if a value is undefined
+ * @param obj - The value to check
+ * @returns True if the value is undefined, false otherwise
+ */
+export declare const isUndefined: (obj: unknown) => obj is undefined;
+/**
+ * Type guard that checks if a value is null or undefined
+ * @param val - The value to check
+ * @returns True if the value is null or undefined, false otherwise
+ */
+export declare const isNil: (val: unknown) => val is null | undefined;
+/**
+ * Type guard that checks if a value is an object (excluding null)
+ * @param val - The value to check
+ * @returns True if the value is a non-null object, false otherwise
+ */
+export declare const isObject: (val: unknown) => val is Record<PropertyKey, unknown>;
+/**
+ * Type guard that checks if a value is a plain object (not a class instance or array)
+ * Determines if an object is a simple key-value store created by object literals
+ *
+ * @param val - The value to check
+ * @returns True if the value is a plain object, false otherwise
+ * @example
+ * ```ts
+ * isPlainObject({}) // true
+ * isPlainObject(new Class()) // false
+ * isPlainObject([]) // false
+ * ```
+ */
+export declare const isPlainObject: (val: unknown) => val is Record<string, unknown>;
+/**
+ * Type guard that checks if a value is a function
+ * @param val - The value to check
+ * @returns True if the value is a function, false otherwise
+ */
+export declare const isFunction: (val: unknown) => val is Function;
+/**
+ * Type guard that checks if a value is a string
+ * @param val - The value to check
+ * @returns True if the value is a string, false otherwise
+ */
+export declare const isString: (val: unknown) => val is string;
+/**
+ * Type guard that checks if a value is a number
+ * @param val - The value to check
+ * @returns True if the value is a number, false otherwise
+ */
+export declare const isNumber: (val: unknown) => val is number;
+/**
+ * Checks if an array is empty
+ * @param array - The array to check
+ * @returns True if the array has no elements, false otherwise
+ */
+export declare const isEmpty: (array: unknown[]) => boolean;
+/**
+ * Type guard that checks if a value is a symbol
+ * @param val - The value to check
+ * @returns True if the value is a symbol, false otherwise
+ */
+export declare const isSymbol: (val: unknown) => val is symbol;
+/**
+ * Ensures a path starts with a leading slash
+ * @param path - The path to process
+ * @returns The path with a leading slash, or empty string if path is undefined
+ * @example
+ * ```ts
+ * addLeadingSlash('test') // '/test'
+ * addLeadingSlash('/test') // '/test'
+ * ```
+ */
+export declare const addLeadingSlash: (path?: string) => string;
+/**
+ * Normalizes a path by ensuring:
+ * - Starts with a single slash
+ * - No trailing slashes
+ * - No consecutive slashes
+ *
+ * @param path - The path to normalize
+ * @returns The normalized path
+ * @example
+ * ```ts
+ * normalizePath('//test//') // '/test'
+ * normalizePath('test/path//') // '/test/path'
+ * ```
+ */
+export declare const normalizePath: (path?: string) => string;
+/**
+ * Removes the trailing slash from a path
+ * @param path - The path to process
+ * @returns The path without a trailing slash
+ * @example
+ * ```ts
+ * stripEndSlash('/test/') // '/test'
+ * stripEndSlash('/test') // '/test'
+ * ```
+ */
+export declare const stripEndSlash: (path: string) => string;
+/**
+ * Checks if a value is a constructor function
+ * A constructor function must:
+ * - Be a function
+ * - Have a prototype
+ * - Have prototype properties beyond the default ones
+ *
+ * @param val - The value to check
+ * @returns True if the value is a constructor function, false otherwise
+ * @example
+ * ```ts
+ * class Test {}
+ * isConstructor(Test) // true
+ * isConstructor(() => {}) // false
+ * ```
+ */
+export declare const isConstructor: (val: unknown) => boolean;

package/dist/utils/index.d.ts

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

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "honestjs",
+	"version": "0.1.0",
+	"author": "Orkhan Karimov <karimovok1@gmail.com> (https://github.com/kerimovok)",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/honestjs/honest.git"
+	},
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"devDependencies": {
+		"@types/bun": "latest",
+		"prettier": "3.5.3"
+	},
+	"peerDependencies": {
+		"hono": "^4",
+		"typescript": "^5",
+		"reflect-metadata": "^0.2.2"
+	},
+	"description": "Nest.js inspired framework for Hono.js",
+	"files": [
+		"dist"
+	],
+	"homepage": "https://github.com/honestjs/honest",
+	"keywords": [
+		"nodejs",
+		"bun",
+		"deno",
+		"javascript",
+		"typescript",
+		"node",
+		"framework",
+		"web-framework",
+		"hono",
+		"nest",
+		"honest"
+	],
+	"license": "MIT",
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org"
+	},
+	"scripts": {
+		"clean": "rm -rf dist",
+		"build": "bun run clean && bun build ./src/index.ts --outdir=dist --target=node --minify --external hono --external reflect-metadata && bun run build:types",
+		"build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+		"format": "prettier --write .",
+		"format:check": "prettier --check ."
+	},
+	"type": "module",
+	"types": "dist/index.d.ts"
+}