honest-node 1.0.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,277 @@
+<p align="center">
+  <a href="https://github.com/honestjs/" target="blank"><img src="https://honestjs.dev/images/honestjs.png" width="120" alt="Honest.js 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>
+
+<p align="center">
+	<a href="https://github.com/honestjs/website">
+		<u>website</u>
+	</a>
+</p>
+
+<p align="center">
+	<a href="https://github.com/honestjs/examples">
+		<u>examples</u>
+	</a>
+	|
+	<a href="https://github.com/honestjs/templates">
+		<u>templates</u>
+	</a>
+</p>
+
+<p align="center">
+	<a href="https://github.com/honestjs/middleware">
+		<u>middleware</u>
+	</a>
+	|
+	<a href="https://github.com/honestjs/guards">
+		<u>guards</u>
+	</a>
+	|
+	<a href="https://github.com/honestjs/pipes">
+		<u>pipes</u>
+	</a>
+	|
+	<a href="https://github.com/honestjs/filters">
+		<u>filters</u>
+	</a>
+</p>
+
+<p align="center">
+	<a href="https://github.com/honestjs/http-essentials">
+		<u>http-essentials</u>
+	</a>
+</p>
+
+<hr />
+
+<div align="center">
+
+[![GitHub](https://img.shields.io/github/license/honestjs/honest)](https://github.com/honestjs/honest/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/honestjs)](https://www.npmjs.com/package/honestjs)
+[![npm](https://img.shields.io/npm/dm/honestjs)](https://www.npmjs.com/package/honestjs)
+[![Bundle Size](https://img.shields.io/bundlephobia/min/honestjs)](https://bundlephobia.com/result?p=honestjs)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/honestjs)](https://bundlephobia.com/result?p=honestjs)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/honestjs/honest)](https://github.com/honestjs/honest/pulse)
+[![GitHub last commit](https://img.shields.io/github/last-commit/honestjs/honest)](https://github.com/honestjs/honest/commits/main)
+[![Discord badge](https://img.shields.io/discord/1482150663432442026?label=Discord&logo=Discord)](https://discord.gg/g3TUeXbeq)
+
+</div>
+
+## Cursor / Agent skills
+
+Install the Honest skill so your editor agent (e.g. Cursor) can use Honest-specific guidance:
+
+```bash
+bunx skills add https://github.com/honestjs/skills --skill honest
+```
+
+See [honestjs/skills](https://github.com/honestjs/skills) for details.
+
+> 🚨 **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.
+
+> ⚠️ **Documentation is not yet complete** ⚠️
+>
+> If you find any issues or have suggestions for improvements, please open an issue or submit a pull request. See
+> [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community
+> guidelines.
+
+## Quick Start
+
+```bash
+bun add -g @honestjs/cli
+honestjs new my-project    # alias: honest, hnjs; interactive template picker
+cd my-project
+bun dev
+```
+
+Templates: **blank** (minimal), **barebone** (modules + services — best for APIs), **mvc** (full-stack with Hono JSX
+views). Use `-t barebone -y` to skip prompts.
+
+See **[Getting Started](https://honestjs.dev/docs/getting-started)** on [honestjs.dev](https://honestjs.dev) for the
+full tutorial, and **[FAQ](https://honestjs.dev/docs/faq)** /
+**[Troubleshooting](https://honestjs.dev/docs/troubleshooting)** for common questions and edge cases.
+
+## Features
+
+- **🚀 High performance** — Built on Hono for maximum speed and minimal overhead.
+- **🏗️ Familiar architecture** — Decorator-based API inspired by NestJS; TypeScript-first.
+- **💉 Dependency injection** — Built-in DI container for clean, testable code and automatic wiring.
+- **🔌 Plugin system** — Extend the app with custom plugins, middleware, pipes, and filters. Plugins run in
+  `options.plugins` order; wrapped entries may attach `preProcessors` / `postProcessors` and optional `name` for
+  diagnostics.
+- **🛣️ Advanced routing** — Prefixes, API versioning, and nested route organization.
+- **🛡️ Request pipeline** — Middleware, guards, pipes, and filters at app, controller, or handler level.
+- **🧪 Lightweight testing harness** — Helpers for application, controller, and service-level tests.
+- **🧭 Startup guide mode** — Actionable diagnostics hints for startup failures.
+- **📝 TypeScript-first** — Strong typing and great IDE support out of the box.
+- **🖥️ MVC & SSR** — Full-stack apps with Hono JSX views; use the `mvc` template or the docs.
+
+### In code
+
+```typescript
+import 'reflect-metadata'
+import { Application, Controller, Get, Module, Service } from 'honestjs'
+import { LoggerMiddleware } from '@honestjs/middleware'
+import { AuthGuard } from '@honestjs/guards'
+import { ValidationPipe } from '@honestjs/pipes'
+import { HttpExceptionFilter } from '@honestjs/filters'
+import { ApiDocsPlugin } from '@honestjs/api-docs-plugin'
+
+@Service()
+class AppService {
+	hello(): string {
+		return 'Hello, Honest!'
+	}
+}
+
+@Controller()
+class AppController {
+	constructor(private readonly appService: AppService) {}
+
+	@Get()
+	hello() {
+		return this.appService.hello()
+	}
+}
+
+@Module({
+	controllers: [AppController],
+	services: [AppService]
+})
+class AppModule {}
+
+const { app, hono } = await Application.create(AppModule, {
+	startupGuide: { verbose: true },
+	debug: {
+		routes: true,
+		plugins: true,
+		pipeline: true,
+		di: true,
+		startup: true
+	},
+	logger: myLogger,
+	strict: { requireRoutes: true },
+	deprecations: { printPreV1Warning: true },
+	container: myContainer,
+	hono: {
+		strict: true,
+		router: customRouter
+	},
+	routing: {
+		prefix: 'api',
+		version: 1
+	},
+	// Components: use class (e.g. AuthGuard) or instance (e.g. new LoggerMiddleware()) to pass options
+	components: {
+		middleware: [new LoggerMiddleware()],
+		guards: [AuthGuard],
+		pipes: [ValidationPipe],
+		filters: [HttpExceptionFilter]
+	},
+	plugins: [
+		new RPCPlugin(),
+		new ApiDocsPlugin(),
+		{
+			plugin: MyPlugin,
+			name: 'core',
+			preProcessors: [pre],
+			postProcessors: [post]
+		},
+		{ plugin: MetricsPlugin, name: 'metrics' }
+	],
+	onError: (err, c) => c.json({ error: err.message }, 500),
+	notFound: (c) => c.json({ error: 'Not found' }, 404)
+})
+
+export default hono
+```
+
+Controllers, services, and modules are wired by decorators; use **guards** for auth, **pipes** for validation, and
+**filters** for error handling. See the [documentation](https://honestjs.dev/docs/overview) for details.
+
+## Runtime Metadata Isolation
+
+Decorator metadata is still collected globally, but each application instance now runs on an immutable metadata snapshot
+captured during startup. This prevents metadata mutations made after bootstrap from changing behavior in already-running
+applications.
+
+## Plugin order
+
+Plugins run in the order they appear in `options.plugins`. Put producer plugins (for example RPC) before consumers (for
+example API docs) when one plugin depends on another’s app-context output.
+
+## Testing harness
+
+Honest exports lightweight helpers for common test setups.
+
+```typescript
+import { createControllerTestApplication, createServiceTestContainer, createTestApplication } from 'honestjs'
+
+const app = await createTestApplication({
+	controllers: [UsersController],
+	services: [UsersService]
+})
+
+const response = await app.request('/users')
+
+const controllerApp = await createControllerTestApplication({
+	controller: UsersController
+})
+
+const services = createServiceTestContainer({
+	preload: [UsersService],
+	overrides: [{ provide: UsersService, useValue: mockUsersService }]
+})
+```
+
+### Running tests in this package
+
+This repo uses [Bun's test runner](https://bun.sh/docs/cli/test). From the package root:
+
+- `bun test` — run all tests once
+- `bun test --watch` — watch mode
+- `bun test <pattern>` — limit to matching file or test names (for example `bun test application.bootstrap`)
+- `bun run test:coverage` — same suite with coverage (summary in the terminal and `coverage/lcov.info`)
+
+Co-locate tests as `*.test.ts` next to sources. Import `reflect-metadata` first in any file that loads decorated
+classes, same as in application code.
+
+Integration-style cases use `*.integration.test.ts` where the whole `Application` stack is exercised (for example the
+request pipeline). Shared HTTP fixtures for application tests live under `src/testing/fixtures/` as **factory
+functions** so each test gets fresh decorator metadata after `MetadataRegistry.clear()` in `afterEach`.
+
+## Startup diagnostics guide mode
+
+Enable startup guidance to get actionable remediation hints when initialization fails.
+
+```typescript
+await Application.create(AppModule, {
+	startupGuide: true
+})
+
+await Application.create(AppModule, {
+	startupGuide: { verbose: true }
+})
+```
+
+Guide mode emits startup diagnostics hints for common issues such as missing decorators, strict no-routes startup, and
+metadata issues.
+
+## License
+
+MIT © [Orkhan Karimov](https://github.com/kerimovok)

package/dist/app.d.ts

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

package/dist/app.js

@@ -0,0 +1,36 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Application, Controller, Get, Module, Service } from '.';
+import { serve } from '@hono/node-server';
+let UsersController = class UsersController {
+    getUsers() {
+        return { users: [] };
+    }
+};
+__decorate([
+    Get(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], UsersController.prototype, "getUsers", null);
+UsersController = __decorate([
+    Controller('users')
+], UsersController);
+let AppModule = class AppModule {
+};
+AppModule = __decorate([
+    Module({
+        controllers: [UsersController]
+    })
+], AppModule);
+const { hono } = await Application.create(AppModule);
+serve(hono, (info) => {
+    console.log(`Listening on http://localhost:${info.port}`); // Listening on http://localhost:3000
+});

package/dist/application/plugin-entries.d.ts

@@ -0,0 +1,13 @@
+import type { IPlugin, PluginEntry, PluginProcessor } from '../interfaces';
+import type { Constructor } from '../types';
+export declare const DEFAULT_PLUGIN_NAME = "AnonymousPlugin";
+export interface NormalizedPluginEntry {
+    plugin: IPlugin;
+    name: string;
+    preProcessors: PluginProcessor[];
+    postProcessors: PluginProcessor[];
+}
+export declare function resolvePlugin(pluginType: Constructor<IPlugin> | IPlugin): IPlugin;
+export declare function resolvePluginName(plugin: IPlugin, index: number, override?: string): string;
+export declare function normalizePluginEntry(entry: PluginEntry, index: number): NormalizedPluginEntry;
+export declare function normalizePluginEntries(plugins: PluginEntry[] | undefined): NormalizedPluginEntry[];

package/dist/application/plugin-entries.js

@@ -0,0 +1,38 @@
+import { isConstructor } from '../utils';
+export const DEFAULT_PLUGIN_NAME = 'AnonymousPlugin';
+export function resolvePlugin(pluginType) {
+    if (isConstructor(pluginType)) {
+        return new pluginType();
+    }
+    return pluginType;
+}
+export function resolvePluginName(plugin, index, override) {
+    const resolved = override || plugin.meta?.name || plugin.constructor?.name;
+    if (!resolved || resolved === DEFAULT_PLUGIN_NAME) {
+        return `${DEFAULT_PLUGIN_NAME}#${index + 1}`;
+    }
+    return resolved;
+}
+export function normalizePluginEntry(entry, index) {
+    if (entry && typeof entry === 'object' && 'plugin' in entry) {
+        const obj = entry;
+        const plugin = resolvePlugin(obj.plugin);
+        const name = resolvePluginName(plugin, index, obj.name);
+        return {
+            plugin,
+            name,
+            preProcessors: obj.preProcessors ?? [],
+            postProcessors: obj.postProcessors ?? []
+        };
+    }
+    const plugin = resolvePlugin(entry);
+    return {
+        plugin,
+        name: resolvePluginName(plugin, index),
+        preProcessors: [],
+        postProcessors: []
+    };
+}
+export function normalizePluginEntries(plugins) {
+    return (plugins ?? []).map((entry, index) => normalizePluginEntry(entry, index));
+}

package/dist/application/startup-guide.d.ts

@@ -0,0 +1,4 @@
+import type { HonestOptions, ILogger } from '../interfaces';
+import type { Constructor } from '../types';
+export declare function createStartupGuideHints(errorMessage: string): string[];
+export declare function emitStartupGuide(logger: ILogger, startupGuide: HonestOptions['startupGuide'], error: unknown, rootModule: Constructor): void;

package/dist/application/startup-guide.js

@@ -0,0 +1,53 @@
+export function createStartupGuideHints(errorMessage) {
+    const hints = new Set();
+    hints.add('Check module wiring: root module imports, controllers, and services should be registered correctly.');
+    if (errorMessage.includes('not decorated with @Controller()')) {
+        hints.add('Add @Controller() to the class or remove it from module.controllers.');
+    }
+    if (errorMessage.includes('has no route handlers')) {
+        hints.add('Add at least one HTTP method decorator such as @Get() or @Post() in the controller.');
+    }
+    if (errorMessage.includes('not decorated with @Service()')) {
+        hints.add('Add @Service() to injectable classes used in constructor dependencies.');
+    }
+    if (errorMessage.includes('constructor metadata is missing') || errorMessage.includes('reflect-metadata')) {
+        hints.add("Import 'reflect-metadata' in your entry file and enable 'emitDecoratorMetadata' in tsconfig.");
+    }
+    if (errorMessage.includes('Strict mode: no routes were registered')) {
+        hints.add('Disable strict.requireRoutes for empty modules, or add a controller with at least one route.');
+    }
+    return [...hints];
+}
+export function emitStartupGuide(logger, startupGuide, error, rootModule) {
+    if (!startupGuide) {
+        return;
+    }
+    const verbose = typeof startupGuide === 'object' && Boolean(startupGuide.verbose);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const hints = createStartupGuideHints(errorMessage);
+    logger.emit({
+        level: 'warn',
+        category: 'startup',
+        message: 'Startup guide',
+        details: {
+            rootModule: rootModule.name,
+            errorMessage,
+            hints,
+            verbose
+        }
+    });
+    if (verbose) {
+        logger.emit({
+            level: 'warn',
+            category: 'startup',
+            message: 'Startup guide (verbose)',
+            details: {
+                steps: [
+                    'Verify decorators are present for controllers/services used by DI and routing.',
+                    "Ensure 'reflect-metadata' is imported once at entry and 'emitDecoratorMetadata' is enabled.",
+                    'Enable debug.startup for extra startup diagnostics and timing details.'
+                ]
+            }
+        });
+    }
+}

package/dist/application-context.d.ts

@@ -0,0 +1,13 @@
+import type { IApplicationContext } from './interfaces';
+/**
+ * Map-backed implementation of the app-level registry.
+ * Used by Application so the app (bootstrap, services, any code with `app`) can share pipeline data by key.
+ */
+export declare class ApplicationContext implements IApplicationContext {
+    private readonly store;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    keys(): IterableIterator<string>;
+}

package/dist/application-context.js

@@ -0,0 +1,22 @@
+/**
+ * Map-backed implementation of the app-level registry.
+ * Used by Application so the app (bootstrap, services, any code with `app`) can share pipeline data by key.
+ */
+export class ApplicationContext {
+    store = new Map();
+    get(key) {
+        return this.store.get(key);
+    }
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    keys() {
+        return this.store.keys();
+    }
+}

package/dist/application.d.ts

@@ -0,0 +1,34 @@
+import { Hono } from 'hono';
+import type { DiContainer, HonestOptions, IApplicationContext, IMetadataRepository, RouteInfo } from './interfaces';
+import type { Constructor } from './types';
+/**
+ * Main application class for the Honest framework.
+ *
+ * All per-app runtime state (routes, global components, DI container) is
+ * instance-based. Static decorator metadata lives in MetadataRegistry and
+ * is shared across all Application instances in the same process.
+ */
+export declare class Application {
+    private readonly hono;
+    private readonly container;
+    private readonly context;
+    private readonly routeRegistry;
+    private readonly metadataRepository;
+    private readonly componentManager;
+    private readonly routeManager;
+    private readonly logger;
+    private readonly options;
+    constructor(options: HonestOptions | undefined, metadataRepository: IMetadataRepository);
+    private setupErrorHandlers;
+    private shouldEmitRouteDiagnostics;
+    private emitStartupGuide;
+    register(moduleClass: Constructor): Promise<Application>;
+    static create(rootModule: Constructor, options?: HonestOptions): Promise<{
+        app: Application;
+        hono: Hono;
+    }>;
+    getApp(): Hono;
+    getContainer(): DiContainer;
+    getContext(): IApplicationContext;
+    getRoutes(): ReadonlyArray<RouteInfo>;
+}