honestjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Orkhan Karimov <karimovok1@gmail.com> (https://github.com/kerimovok)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# Honest Framework
+
+<p align="center">
+  <a href="https://github.com/honestjs/" target="blank"><img src="https://avatars.githubusercontent.com/u/197956909" width="120" alt="Honest Logo" /></a>
+</p>
+<p align="center">
+A modern, TypeScript-first web framework built on top of <a href="https://hono.dev/" target="blank">Hono</a>, designed for building scalable and
+maintainable web applications. Honest combines the elegance and architecture of <a href="https://nestjs.com/" target="blank">Nest</a> with the
+ultra-fast performance of Hono, giving you the best of both worlds.
+</p>
+
+> ⚠️ **Early Development Warning**
+>
+> Honest is currently in early development (pre-v1.0.0). Please be aware that:
+>
+> - The API is not stable and may change frequently
+> - Breaking changes can occur between minor versions
+> - Some features might be incomplete or missing
+> - Documentation may not always be up to date
+>
+> We recommend not using it in production until v1.0.0 is released.
+
+## Features
+
+- 🚀 **High Performance** - Built on top of the ultra-fast Hono framework
+- 📦 **Modular Architecture** - Organize your code into reusable, feature-focused modules
+- 💉 **Dependency Injection** - Built-in DI container for better code organization and testing
+- 🔌 **Plugin System** - Extend functionality through a flexible plugin system
+- 🛣️ **Advanced Routing** - Support for versioning, prefixes, and nested routes
+- 🔒 **Built-in Security** - Guards, middleware, and error handling out of the box
+- 🔄 **Request Pipeline** - Powerful middleware, guards, pipes, and filters
+- 📝 **TypeScript-First** - Built with TypeScript for excellent type safety and IDE support
+
+## Quick Start
+
+### Using Honest CLI _(Coming Soon)_
+
+The fastest way to create a new Honest application is to use the Honest CLI:
+
+```bash
+# Install Honest CLI globally
+bun add -g @honestjs/cli
+# or
+pnpm add -g @honestjs/cli
+# or
+yarn global add @honestjs/cli
+# or
+npm install -g @honestjs/cli
+
+# Create a new project
+honest new my-project
+cd my-project
+
+# Start the development server
+bun dev
+```
+
+This will create a new project with a standard directory structure and all necessary configuration files.
+
+### Manual Setup
+
+If you prefer to set up your project manually, follow these steps:
+
+1. Install packages
+
+```bash
+bun add honestjs hono reflect-metadata
+# or
+pnpm add honestjs hono reflect-metadata
+# or
+yarn add honestjs hono reflect-metadata
+# or
+npm install honestjs hono reflect-metadata
+```
+
+2. Create your first controller:
+
+```typescript
+// app.controller.ts
+import { Controller, Get } from 'honestjs'
+
+@Controller()
+class AppController {
+	@Get()
+	helloWorld() {
+		return 'Hello, World!'
+	}
+}
+
+export default AppController
+```
+
+3. Create a module:
+
+```typescript
+// app.module.ts
+import { Module } from 'honestjs'
+import { AppController } from './app.controller.ts'
+
+@Module({
+	controllers: [AppController]
+})
+class AppModule {}
+
+export default AppModule
+```
+
+4. Bootstrap your application:
+
+```typescript
+import 'reflect-metadata'
+import { Application } from 'honestjs'
+import { AppModule } from './app.module'
+
+const { app, hono } = await Application.create(AppModule, {
+	routing: {
+		prefix: 'api',
+		version: 1
+	}
+})
+
+export default hono
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/application.d.ts

@@ -0,0 +1,124 @@
+import { Hono } from 'hono';
+import type { HonestOptions, RouteInfo } from './interfaces';
+import type { Constructor } from './types';
+/**
+ * Main application class for the Honest framework
+ * Serves as the entry point for creating and configuring web applications
+ *
+ * Features:
+ * - Module-based architecture for organizing application components
+ * - Dependency injection container integration
+ * - Plugin system for extending functionality
+ * - Route management with versioning support
+ * - Global error handling
+ *
+ * @example
+ * ```ts
+ * const { app } = await Application.create(AppModule, {
+ *   routing: { prefix: '/api', version: 1 },
+ *   plugins: [new LoggerPlugin()]
+ * });
+ * ```
+ */
+export declare class Application {
+    private readonly hono;
+    private readonly container;
+    private readonly routeManager;
+    private readonly options;
+    /**
+     * Creates a new Application instance with the specified configuration
+     * @param options - Configuration options for the application
+     * @param options.routing - Route configuration (prefix, versioning)
+     * @param options.plugins - Array of plugins to extend functionality
+     * @param options.container - Custom dependency injection container
+     * @param options.hono - Hono-specific configuration options
+     * @throws {Error} If options are invalid or initialization fails
+     */
+    constructor(options?: HonestOptions);
+    /**
+     * Sets up global components from application options
+     * Initializes the component manager and registers global middleware,
+     * guards, pipes, and filters
+     * @private
+     */
+    private setupComponents;
+    /**
+     * Sets up global error handlers for the application
+     * Configures handlers for 404 Not Found and general error cases
+     * @private
+     */
+    private setupErrorHandlers;
+    /**
+     * Resolves a plugin from either a constructor or instance
+     * @param pluginType - Plugin constructor or instance
+     * @returns Resolved plugin instance
+     * @private
+     * @throws {Error} If plugin instantiation fails
+     */
+    private resolvePlugin;
+    /**
+     * Registers a module with the application
+     * Processes the module's metadata and registers its controllers
+     *
+     * @param moduleClass - The module class to register
+     * @returns The application instance for method chaining
+     * @throws {Error} If module registration fails
+     *
+     * @example
+     * ```ts
+     * const app = new Application();
+     * await app.register(UsersModule)
+     *         .register(AuthModule);
+     * ```
+     */
+    register(moduleClass: Constructor): Promise<Application>;
+    /**
+     * Creates and initializes a new application with a root module
+     *
+     * Process:
+     * 1. Creates application instance with provided options
+     * 2. Initializes and runs plugin lifecycle hooks
+     * 3. Registers the root module
+     * 4. Returns both the application and Hono instances
+     *
+     * @param rootModule - The root module class for the application
+     * @param options - Application configuration options
+     * @returns Object containing the application and Hono instances
+     * @throws {Error} If application creation or module registration fails
+     *
+     * @example
+     * ```ts
+     * const { app, hono } = await Application.create(AppModule, {
+     *   routing: { prefix: '/api' }
+     * });
+     * ```
+     */
+    static create(rootModule: Constructor, options?: HonestOptions): Promise<{
+        app: Application;
+        hono: Hono;
+    }>;
+    /**
+     * Gets the underlying Hono instance for direct access
+     * Use this method when you need to access Hono-specific features
+     *
+     * @returns The Hono application instance
+     * @example
+     * ```ts
+     * const hono = app.getApp();
+     * hono.use(someHonoMiddleware());
+     * ```
+     */
+    getApp(): Hono;
+    /**
+     * Gets information about all registered routes in the application
+     * Useful for documentation and debugging purposes
+     *
+     * @returns Array of route information objects (read-only)
+     * @example
+     * ```ts
+     * const routes = app.getRoutes();
+     * console.log(routes.map(r => r.path));
+     * ```
+     */
+    getRoutes(): ReadonlyArray<RouteInfo>;
+}

package/dist/constants/index.d.ts

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

package/dist/constants/version.constants.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Symbol to use when marking a route as version-neutral
+ * Version-neutral routes are accessible both with and without version prefix
+ */
+export declare const VERSION_NEUTRAL: unique symbol;

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

@@ -0,0 +1,9 @@
+import type { ControllerOptions } from '../interfaces';
+/**
+ * Decorator that marks a class as a controller
+ * Controllers are responsible for handling incoming requests and returning responses
+ * @param route - The base route for all endpoints in this controller
+ * @param options - Configuration options for the controller
+ * @returns A class decorator function
+ */
+export declare function Controller(route?: string, options?: ControllerOptions): ClassDecorator;

package/dist/decorators/http-method.decorator.d.ts

@@ -0,0 +1,43 @@
+/**
+ * GET method decorator
+ * The GET method requests a representation of the specified resource.
+ * Requests using GET should only retrieve data and should not contain a request content.
+ * @param path - The route path
+ */
+export declare const Get: (path?: string, options?: import("..").HttpMethodOptions) => MethodDecorator;
+/**
+ * POST method decorator
+ * The POST method submits an entity to the specified resource,
+ * often causing a change in state or side effects on the server.
+ * @param path - The route path
+ */
+export declare const Post: (path?: string, options?: import("..").HttpMethodOptions) => MethodDecorator;
+/**
+ * PUT method decorator
+ * The PUT method replaces all current representations of the target resource with the request content.
+ * @param path - The route path
+ */
+export declare const Put: (path?: string, options?: import("..").HttpMethodOptions) => MethodDecorator;
+/**
+ * DELETE method decorator
+ * The DELETE method deletes the specified resource.
+ * @param path - The route path
+ */
+export declare const Delete: (path?: string, options?: import("..").HttpMethodOptions) => MethodDecorator;
+/**
+ * PATCH method decorator
+ * The PATCH method applies partial modifications to a resource.
+ * @param path - The route path
+ */
+export declare const Patch: (path?: string, options?: import("..").HttpMethodOptions) => MethodDecorator;
+/**
+ * OPTIONS method decorator
+ * The OPTIONS method describes the communication options for the target resource.
+ * @param path - The route path
+ */
+export declare const Options: (path?: string, options?: import("..").HttpMethodOptions) => MethodDecorator;
+/**
+ * ALL method decorator (matches all HTTP methods)
+ * @param path - The route path
+ */
+export declare const All: (path?: string, options?: import("..").HttpMethodOptions) => MethodDecorator;

package/dist/decorators/index.d.ts

@@ -0,0 +1,10 @@
+export * from './controller.decorator';
+export * from './http-method.decorator';
+export * from './module.decorator';
+export * from './parameter.decorator';
+export * from './service.decorator';
+export * from './use-component.decorator';
+export * from './use-filters.decorator';
+export * from './use-guards.decorator';
+export * from './use-middleware.decorator';
+export * from './use-pipes.decorator';

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

@@ -0,0 +1,8 @@
+import type { ModuleOptions } from '../interfaces';
+/**
+ * Decorator that marks a class as a module
+ * Modules are used to organize the application structure and dependencies
+ * @param options - Configuration options for the module
+ * @returns A class decorator function
+ */
+export declare function Module(options?: ModuleOptions): ClassDecorator;

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

@@ -0,0 +1,41 @@
+/**
+ * Decorator that binds the request body to a parameter
+ * @param data - Optional property name to extract from the body
+ */
+export declare const Body: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Decorator that binds a route parameter to a parameter
+ * @param data - The parameter name in the route
+ */
+export declare const Param: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Decorator that binds a query parameter to a parameter
+ * @param data - The query parameter name
+ */
+export declare const Query: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Decorator that binds a header value to a parameter
+ * @param data - The header name
+ */
+export declare const Header: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Decorator that binds the request object to a parameter
+ */
+export declare const Req: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+export declare const Request: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Decorator that binds the response object to a parameter
+ */
+export declare const Res: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+export declare const Response: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Decorator that binds the context object to a parameter
+ */
+export declare const Ctx: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+export declare const Context: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Decorator that binds a context variable to a parameter
+ * @param data - The variable name to retrieve from context
+ */
+export declare const Var: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
+export declare const Variable: (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;

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/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-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-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-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-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/di/contrainer.d.ts

@@ -0,0 +1,23 @@
+import type { DiContainer } from '../interfaces';
+import type { Constructor } from '../types';
+/**
+ * Dependency Injection container that manages class instances and their dependencies
+ */
+export declare class Container implements DiContainer {
+    /**
+     * Map of class constructors to their instances
+     */
+    private instances;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/di/index.d.ts

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

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

@@ -0,0 +1,31 @@
+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: Error, c: Context) => Promise<Response & import("hono").TypedResponse<{
+        response: {
+            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;
+        };
+        status: import("hono/utils/http-status").ContentfulStatusCode;
+    }, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
+}

package/dist/handlers/index.d.ts

@@ -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/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: Error, context: Context, options?: {
+    status?: number;
+    title?: string;
+    detail?: string;
+    code?: string;
+    additionalDetails?: Record<string, any>;
+}): {
+    response: ErrorResponse;
+    status: ContentfulStatusCode;
+};

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;

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 = any>(type: string, factory?: (data: any, ctx: Context) => T): (data?: any) => (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;

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/index.d.ts

@@ -0,0 +1,19 @@
+import 'reflect-metadata';
+export * from './application';
+export * from './constants';
+export * from './decorators';
+export * from './di';
+export * from './handlers';
+export * from './helpers';
+export * from './interfaces';
+export * from './managers';
+export * from './registries';
+export * from './types';
+export * from './utils';
+declare global {
+    namespace Reflect {
+        function getMetadata(metadataKey: string, target: object): any;
+        function defineMetadata(metadataKey: string, metadataValue: any, target: object): void;
+        function hasMetadata(metadataKey: string, target: object): boolean;
+    }
+}